[wp-hackers] Inline Documentation Effort was a Failure
wordpress at santosj.name
Sat May 24 21:46:49 GMT 2008
Forking WordPress is a joke, which I have difficultly explaining well.
If I forked WordPress, it would quickly fall behind the official
WordPress feature set, bug fix, and support.
The goal was never to force the issue, because I understood that was
unachievable. The goal was to put forth a new "toy" and see if the
criteria listed before would be implemented. What you stated is
absolutely correct and I already knew that. I'm stating that my personal
expectations and experiment was a failure and listed the reasons why.
For future reference for anyone who wishes to take up the effort in the
future and what the expectations were at this point of time.
The entire Inline Documentation Effort was based on the premise that the
codex does not have every function and WordPress API documented. I've
looked at the WordPress Codex and I couldn't find everything I was
looking for and some of the stuff I did find was out of date.
The Inline Documentation Effort was to document something that is small,
relatively quickly documented when compared to documenting the same code
on the Codex, which requires more descriptions (preferably with proper
grammar and simple English) use cases, and examples. The Shortcodes
Codex Page is a good example of proper API documentation. I'm unsure how
long it took, but it wouldn't have take as long to write inline
documentation for the Shortcodes functions (a lot of the functions would
only had required short descriptions).
The Inline Documentation Effort was also based on the theory that since
the inline documentation is located right where the code is, it would be
easier to maintain the documentation and keep it up to date unlike on
some of the Codex pages.
As others have stated, I think I will try again and then see where it
goes. If it again fails, well at least I'll be able to put on my resume
that I know all of WordPress and not many can say that.
I have to agree with DD32, the main reason for the failure is that it is
easier to complain about the lack of documentation and do nothing about
it. It is easy to find the solution for ourselves and not tell anyone
else about it (or just blog about it).
The problem is that if the inline documentation remains in the WordPress
source, the conversations will instead turn from complaining about the
lack of documentation to complaining about how the inline documentation
is inaccurate. If that is the case, I would rather people complain about
the lack of the documentation than that the current documentation is
You can make the argument that the Codex is not authoritative, but if
the documentation is the source that it is. If you then make the
statement that the inline documentation in the source is not
authoritative also, then you have trust issues or I would assume.
I'm not sure anymore. I don't have 12 years of professional development
experience. I only have a year, but I've been coding for a long time and
I know that for the longest time, inline documentation is what has been
missing. It is generally a good thing.
You are right, no one can force the issue, because this is an open
source community driven project. Or that would be accurate if Automattic
wasn't a for-profit company. I suppose the accurate statement was that I
can't force the issue on the community, which does not work for money.
I'm not part of Automattic which is a private company, so I can't change
That isn't to make light of the awesome members of the community with
the codex and with WordPress that aren't doing a kick ass job. One side
of me acknowledges that there have already been many before me that
tried to put forth the effort to add inline documentation. From that, I
thought it would be easier for others like them to join in and correct
mistakes and add in additional documentation that is needed.
Perhaps I could be like Lorelle is with the Codex and push for more
effort in the inline documentation effort. I just need to find out how
Lorelle does it and mimic it for the effort I'm pushing.
It is hard to criticize the project too much, because I know a lot of
professionalism is being added to WordPress every day. However, I think
in this area there needs to be additional work.
As an aside, I did try to be a good example, but I already stated how
that turned out. Also, as project leader, if your developers don't
listen to you about documentation, then you should slap them, because
they should listen to you no matter their personal preference. Your
title says "project leader," not "maybe they should listen to you, but
eh, it is up to them." Of course, the work environment is different from
the open source one, the project leader doesn't fully have that power.
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.
Eric Marden wrote:
> I applaud your efforts to promote writing phpdoc blocks as a matter of
> programming best practice, but there is a good reason why its not
> being done consistently: the developers (most of whom are volunteers)
> have better things to do. Plain and simple.
> I am a developer with 12 years of professional programming experience.
> My last two positions have been as tech leads, and I have been
> responsible for crafting the standards for my team. And if there is
> something I have learned from that role: you can't force policies on
> developers if they don't see the value in them. There has to be
> universal buy in from all the developers. The other thing I've learned
> is that you don't have to implement all best practices in order to
> have a successful team/project/code base.
> The other thing to keep in mind is that best practices don't look the
> same on every project. In fact, they need to be customized to fit the
> work at hand. Wordpress, both its developers and its fearless leader,
> just happens to prefer documentation living in the Codex instead of
> phpdoc blocks. It gets them more bang for their buck, as more people
> will be using it in their day to day usage than looking at the code.
> I've been building sites and blogs with wordpress since the 1.5 days,
> and have always found the Codex to be more than adequate for my needs.
> In fact I trumpet the wordpress API - as represented by the Codex - as
> the mark of a brilliantly executed open source web app. Sure,
> generated documentation would be helpful to new people looking to
> start committing to the wordpress project, but that's a much smaller
> audience that the people looking to just extend and customize WP for
> their needs. For that group, the codex is just fine, and the WP team
> recognizes that fact. Indeed, this is a primary example of an agile
> development philosophy - and one that resonates with my own
> development methodology. This is obviously a deliberate decision made
> by those stewarding the WP project into the future, and one that works
> fine for 99% of the users.
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
More information about the wp-hackers