[wp-hackers] Inline Documentation Effort was a Failure

[Jacob Santos]

Hmm, it seemed four months away from the effort has given me insight 
into my inquiry on whether the effort would actually be an success. A 
successful condition would be active inline documentation maintenance, 
which means active support of updating current inline documentation and 
when adding new functions, making sure that they also have inline 
documentation (phpdoc).

I do think it is frustrating, I was going to go ahead and restart the 
effort, but updating my repository depressed me. The assumption was that 
one person wouldn't have to continuous keep on top of the documentation 
to make sure it was accurate and add documentation for new functions. 
The attempt was to get others to accept ownership and slowly work 
together to improve the inline documentation.

Reasons The Effort Failed (in my humble opinion):

1. Writing Documentation sucks

Writing user and developer documentation sucks. Writing Inline 
Documentation sucks. As professionals, you have to do what needs to be 
done to provide quality support to the users and developers that come 
after you. Writing documentation might be akin to the 9th circle of 
hell, but knowing that the person that comes after can make it into 
heaven should be all the more worthwhile. Writing documentation isn't 
about you, it is about the next guy who has to read your (ugly) code.

2. Doesn't help when the project leader doesn't see the importance.

I had a conversation with Matt Mullenweg,

"Why doesn't the Shortcodes have documentation?" I asked.

"What do you mean? It does have documentation. Check the codex." Matt 
replied.

Yeah the first place I'm going to look for function documentation is on 
the web. No. The first place I'm going to look is in the code! That 
aside the documentation for the shortcodes in the codex is very good, 
but it is the exception rather than the rule.

3. You can't have majority of the core developers not adding inline 
documentation.

Peter Westwood appears to be the lone core developer, which consistency 
adds inline documentation. I say this from my experience with his 
commits from October 2007 to January 2008. So I'm going to apply my 
assumption based on historical evidence rather than current evidence.

The inline documentation effort is headed for failure unless all of the 
core developers understand that inline documentation is not only 
important, but required. Without it, you have a situation, where some of 
the code has inline documentation and most doesn't. Eventually you'll 
get to a point where most of the inline documentation is either in need 
of updates or most of the functions are in need of phpdoc documentation.

That said, even if all of the functions were documented today, what 
would the situation be two months or two years from now? Pretty terrible.

4. Need better support from the community.

I restarted the effort to keep from having the conversation about adding 
inline documentation and nothing coming from it. I did not ever plan on 
having to maintain the inline documentation and I did not plan on having 
to constantly keep on top of new functions being added.

You can't force anyone to do anything in an open source community. 
Enough people do great things that I doubt inline documentation is a 
major boon or thorn to anyone. Depressing, but I'll rather be coding 
myself thank you.

5. Need rule making it a requirement for patches and for core developers.

I mean, this is implied with 2 and 3, but I came from a project where 
you had to write both inline documentation and DocBook documentation. It 
was a pain in the ass, but at the end of the day, it was worth it, 
because everyone knew what the code was supposed to do.

WordPress didn't become popular, because of inline documentation nor 
will it increase or decrease in popularity, because of it. I just doubt 
that my effort and mission.

If you disagree, then by all means, please take up the effort and prove 
me wrong. Hell, I'll even help prove myself wrong if you will start. If 
no one else does then I'll reconsider the effort for the Fall.

-- 

Jacob Santos

http://www.santosj.name - blog
http://funcdoc.wordpress.com - WordPress Documentation Blog/Guide Licensed under GPLv2

Also known as darkdragon and santosj on WP trac.