[wp-hackers] Inline Documentation Effort was a Failure

[Jacob Santos]

Perhaps I sounded the failure too soon. To be fair, let me state the
conditions of failure and success to be determined at a later date. I
thought about it at the beginning and these are basically what I had in
mind.

I'm not trying to undermine the current accomplishments. The community and
core team has really turned WordPress into a highly respectable
application. However, there is competition out there and WordPress will be
evaluated months and years from now. If the competition has documentation,
has the same features as WordPress, then I'm going to go with the
competition.

I /do/ actually like WordPress, it does many things right and continues to
do so with 2.6. Regardless, the differences between the different blog
platforms are growing smaller.

Conditions of Success:

* Active maintenance of inline documentation from core and/or community
members. (As shown perviously with pluggable.php, this has already failed)

* Function additions either has inline documentation included or patch
afterwards which adds it (I suppose if I change my mind, this would still
continue to be successful. I meaning without my involvement and right now
it is most not doing it).

* Continued improvement of the inline documentation. (Like DD32 said, I'm
also not an expert at grammar and writing composition. Actually, my
documentation sometimes does quite suck.)

* All core developers writing inline documentation.

* Requirement for patches and the core team that any commit/patch requires
inline documentation updates or additions.


With the last two, I mean before Ohloh removed (or changed the location
of) the statistics for the comment to code ratio, Matt had one of the
lowest for the team. I'm not flaming Matt, but it is just how it is from
the previous statistics and it is a fact (well one that can no longer be
reference, but I did do research back in October, so you can take my word
for it or not. I don't care what you think). Not all of it is his fault,
as I found out, Matt commit the shortcodes, but he wasn't the one who
wrote it. So he does shoulder the blame, for some of which is not actually
his.

When the project leader says, "This is how it is going to be." By his word
that is how it is and either you accept it or you join another project
which does it the way you want. To be honest, I accepted the requirement
to write documentation kicking and screaming on the other project.

I'm pretty sure I thought at the time, that there was no way in hell that
the requirement would ever be added that all patches have inline
documentation, which either adds or updates inline documentation that is
needed. My hope was that it wouldn't matter and if enough of WordPress was
documented that the community would jump in and do the right thing for
WordPress.

I knew that it almost needed a culture shift and saying, "Hey, you get the
ball rolling and we'll join you!" I'm not sure I have the Karma to
influence that in the community.

It seems that I should shoot for more completion before I retreat again in
dispair. It would be nice to finally complete a project I started, unlike
the 10 or so personal coding projects I have sitting and waiting for me
once I finish.

I appreciate the support, but you know the prediction that the inline
documentation will go into disrepair in two years time might never happen.
I'll probably fork WordPress long before that happens.

-- 
Jacob Santos

http://www.santosj.name - Personal Blog
http://funcdoc.wordpress.com - WordPress Function Documentation Blog