Tag Archives: Documentation

First Day of WordPress Documentation

Posted by Jacob Santos on May 15, 2008 Comments Off

Well, I’m a few days late with working on the WordPress Documentation. However, I was able to create the repositories I need and converted all of the current documentation to a new Trunk checkout. I’m going to start working more on it later.

I just realized that the project I had for finding all of the WordPress function versions needs to be restarted once more. I need to totally work more on this to make sure that it is done right and that the code is parsed correctly. I’ll rewrite the parser to output XML and then pass over that to get the functions and what not.

I plan on implementing a couple of other features, such as tracking when parameters were added and removed and what version. I also want to track hooks, when they were added, which files, and when/if they were removed. I hope to create a one stop shop for all of the current code tools out there with a bit more reliability.

I also want to take hold and try a Subversion checkout approach, which does everything automatically also. That would be the best bet and try to do something which switches the checkout when a new version comes out.

This will take away from writing documentation, but I’ve been putting this off for a while now and it needs to be done.

Possibly Related Posts:


WordPress Plugin Writing

Posted by Jacob Santos on January 7, 2008 5 comments

The WordPress Function Documentation blog has several posts about the current state of inline documentation.

However, I’m currently writing a daily series on Plugin authoring that will last until I either get bored of writing the series or I run out of ideas. The plan is to write as much as possible on plugin authoring and then eventually move the contents to the codex and to a WordPress Developer Manual.

So far, I’ve dived into the deep end of the WordPress Plugin API, but I’m eventually going to write posts on the add_filter() and friends functions on their usage. Eventually, I want to cover all I can on the Plugin API, which is my “field” that I’ve adopted in WordPress.

I will eventually move on to covering the other subjects, but it really just depends on time.

Each post that I’ve written does not exceed 500 words, which keeps the information concise and to the point. Eventually, I believe creating a larger document for other areas.

While the blog is primarily for function documentation and the progress of inline documentation in WordPress source. I do want to expand to user documentation fields and much like the posts for the Developer Manual, expand on user concepts in order to eventually create an User Manual.

The nice thing about the blog is that when I write a post, I sent the publish date to the next day of the last post. As long as I keep creating a post a day or several every other day, I should have a blog that has a post every day. Well, that will be tested as soon as I start school and WordPress goes into the forethought of my mind.

The goal is not to have a post a day, the goal is to write as much as possible about WordPress documentation to eventually create something bigger.

Please note, the contents of the blog are licensed under GPL v2, therefore all contents are with permission to be used under the restriction of that license. It is impossible to publish modifications back to my blog. I do think it would serve its purpose if you published modifications to the codex or if you so choose to do so at your blog and retain the GPL v2 license for that post.

Possibly Related Posts:


WordPress Documentation Informal and Unofficial Roadmap

Posted by Jacob Santos on December 31, 2007 3 comments

I would totally love it if WordPress had all of its functions documented. It could put WordPress with higher respect with developers. A lot is put on with the Codex, but the Codex is unstructured and doesn’t cover the complete depth of WordPress core and outer edges.

It is true that pieces can be picked up with the codex and trips to the code would allow others to pick up the rest. The WordPress API isn’t as difficult as some applications, so it has done without and flourished without a complete function documentation for a while.

That should change and is changing. However slow, it is quite boring to write documentation and depends on the mood. Realistically, it is very easy to get bored of it after working on it for a few days only to jump back on after taking a break of a few more days.

Documentation Process

For me, the way I’m now writing the documentation is by first going through and adding PHPdoc style documentation to all of the functions and then going back and adding @since information. Well the complete process is as follows.

  1. Add phpdoc style documentation going down the file to all functions and others that can be documented. Usually just a template which I copy and paste.
  2. Going back up I add the function name as well as @since
  3. Going back down I try to add short description information if I can, but definitely the parameters and return type information.
  4. Going back up I complete as much as possible the long description, but definitely the short description.
  5. The long description that is still needed, I usually ignore until it either comes to me or I want to finish the documentation for the file.

It might not seem like much, but on average documenting a function can take anywhere from 10 minutes to between 30 minutes and an hour and the more difficult and longer functions.

Old Style Documentation

There have been attempts to document the code before, but the extent is no where near the level of the documentation process. It is likely that because documentation does cause minor overhead to the PHP execution that a lot of documentation would slow WordPress down. However, that should not keep the documentation from the core.

If someone really cared about removing overhead from comments, then they’ll most likely do premature optimization and remove as much white space as possible also and combine as many files as possible. Premature, as the most overhead is likely with the database.

A few projects have noticed an increase and so have a build environment which has the comments, nice format, and split into multiple files and then through the build process compress and combine the files. If someone wanted to squeeze a few milliseconds, then be my guest.

The Roadmap

To me, it would be a pipe dream to think that all the functions in wp-includes would be documented before WordPress 2.4 comes out. However, I would very much like to complete the documentation in the folder before 2.5 comes out. In that way, the core development team can keep up with documentation themselves and the hardest part would be complete.

The team has started to make sure that any new function that goes in gets documentation, which should stop the flow of undocumented functions. However, it would be better if more people offered to help with the documentation. The standard is there and the support is there.

WordPress 2.4 is moving the business logic from the presentation layer in the admin panel backend. Therefore, those functions should also be documented. Hopefully, I hope to also have those done before 2.5 is out also, but going off what I have currently done and how much I have to go to complete wp-includes, I’ll be pushing for WordPress 2.6.

After the Function Documentation

I plan on focusing more on the unit testing and DocBook type documentation. It would be great to get WordPress to the level where has complete unit test coverage of the WordPress functions. Covering regressions, as well as bugs.

It would put WordPress on a higher level with developers, in my opinion, if I know that whatever code I applied went through unit tests to make sure it didn’t cause any regressions and actually fixed problems.

There is someone working on this and since it is supported by Automattic, should be continued without outside help. It would move the test coverage along if more people helped out, because user testing can only pick up so much.

The next step after the unit tests or automated tests, is acceptance testing. Which would automate portions of problems for users and test for common failures.

With an comprehensive WordPress User Guide and Developer Guide written in DocBook markup, it would allow easy access to common answers to users’ and developers’ questions. It would also remove the need to traverse the sometimes difficult to navigate codex. The guides would also be condense enough to provide pin point details instead of trying to describe everything as much as possible. With shorter amount of text, more people will be more willing to actually read through the sections to where they need to go.

WordPress Documentation Plans

The codex is not bad, but it can be improved for both developers and from the work on the user guide and developer guide, long portions should be moved back to the codex to allow for further modification and improvement.

The best thing about the DocBook User and Developer Guides is that they are completely translatable and multiple versions can be available on the same site for those native users. The User and Developer Guides would prevent translators from having to translate the huge amount of text in the codex to provide simple answers.

It is a hope, but there is only so much time. My attempt is basically to jump start the process, so that others that come after me won’t feel as overwhelmed as I do now. To my knowledge and to those that came before me, I believe they also shared my hope. It might have taken one or two years before I came along and put forth a small amount of effort. However, if I don’t get the documentation finished, I believe that some awesome person will come after me and finish what many others have already started.

Possibly Related Posts:


Even if you can’t write well

Posted by Jacob Santos on November 3, 2007 1 comments

And I speak of this because I’m one of those who can’t write well. The philosophy I’ve always had was that someone would eventually come along, take a look at the crap you wrote and fix it. A novel concept, but I’ve seen it in action.

I try to write documentation well enough, but it is clearly fascinating skill others have to clear issues up and make words and paragraphs look pretty. Organization is key I think. By placing code in certain places, you can give context to paragraphs in a way that just blows the mind.

What I mean is that even if you may not think what you write would help someone, there are enough people that might stumble upon the code to correct the wording. The key with writing documentation is to write well enough for most people to understand what you are trying to get across so that someone who wishes to play editor may do so accurately.

Possibly Related Posts:


Why people who complain won’t write documentation themselves

Posted by santosj on October 23, 2007 2 comments

Summary: “Too lazy, don’t seriously care, not invested enough, or just simply can’t from the lack of programming experience. Someone else doing the documentation writing can gain a lot from the experience, but advocating someone else to do so is a lost cause.”

Read more »

Possibly Related Posts:


Will Documentation Writers Be Remembered?

Posted by santosj on October 21, 2007 1 comments

Probably not. I think the ends far outweigh the perceived gains from being “recognized.” One of the major advantages of PHP is its heavily documented functions and its almost one stop shop for finding everything you’ll need and want to know about a function. I don’t know who those people are, but I have a lot of love for the time and energy they put in.

It is possible to find their names, but I don’t think many would put in the energy. Coincidently, not many will put in the effort to document a project. It just takes too much sweat, blood, and tears.

It is rewarding in the metaphorical sense, and if you have to pay penitence for not documenting past projects. Documenting another’s project is one way to avoid the whip. It is actually relaxing, in the sense that I can spend hours, “Holy crap, it is 3am already? Just a few more hours and then I’ll go to bed.”

The project I’m currently documenting probably be the same. People may thank me without knowing my name, but you know I won’t mind. If only to make up for past mistakes and learn new habits that will better benefit future ones. The reward for me, is the knowledge gained from the insight and from that I think I’m doing myself more good. It is how I can justify non sexy work, such as documentation.

Possibly Related Posts: