[wp-hackers] Inline Documentation Effort was a Failure
wordpress at santosj.name
Thu May 22 03:41:30 GMT 2008
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
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
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
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.
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.
More information about the wp-hackers