[wp-hackers] Inline Documentation Effort was a Failure

[Jacob Santos]

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 
inaccurate.

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 
them either.

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.

-- 

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.



Eric Marden wrote:
> Jacob,
>
> 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.
>
> -e
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers