Monthly Archives: November 2009

Why Writing Documentation Wasn’t a Waste of Time

Posted by Jacob Santos on November 14, 2009 3 comments

The hardest part of writing documentation for WordPress was coming to grips with the realization that I could have been spending that time actually doing something. I put aside three browser based games, a library I was working with someone on, and my core web sites to write inline documentation. That I think was a tremendous sacrifice or so I thought at the time. The motivations for which was that I was helping myself by not having to figure who what each function did, what function I should have used, and where each function was located.

Working with WordPress was filled with so many WTFs, I was almost screaming out loud instead of just inside my head. The API in WordPress is so large, learning it is almost like learning PHP. In fact, there were quite a few times, I built functionality that already existed or to need a solution and find it one or two weeks later. Other parts were so convoluted in functionality, it wasn’t worth tracking down each code branch to figure out what was happening and how I could hook in and change it.

The Codex is great for what it is and continues to be, but it is a community project and much like WordPress is an Open Source project, they both suffer from the same problem. Motivation and the surplus or lack of it. Writing documentation for the codex is a massive project, because you have to explain things so that people can understand. Writing inline documentation, you have no such restrictions.

Inline documentation is technical and to be read by programmers of various skill levels to provide the additional information for understanding what the function is used for. Furthermore, each function, object, or documented code is independent of everything else. With Codex pages, often you must tie in multiple functions to explain a given concept well enough for the layman to understand how they may be used together to create something great.

So, my motivation was that since it would take a fraction of time verses writing Codex information, it would be better to have completed inline documentation that changes with the code than to spend forever writing Codex documentation that has to continue to keep up with the changes of the code and will have a harder time keeping up to date with the code changes after the page has been written.

I believe with the introduction of books that WordPress may be served better by those who wish to write documentation for money than the community benefit. Well, each really will serve each other. Authors of books will have a limited space and thus may only devote as much as they can towards certain topics that help the reader get into the flow and basics of working with WordPress. The Codex goes into more technical information for various subjects dealing sometimes with topics outside of WordPress, but dealing with WordPress. For example, hosting, mod_rewrite, and other hosting techniques that can be used to enhance, secure, and improve the WordPress experience.

Actually, I should note that there were quite a few patches that gave me a leg up during the early parts of the project and towards the end people did help. Now that I’ve done other things, there are still people maintaining the documentation. In the beginning, I had the feeling that everyone wanted someone else to write the documentation, because no one wanted to be tasked with such a long and tedious project. When the choice is doing something you enjoy verses something that doesn’t benefit you but other people, then well it is understandable. My prediction was that once someone had put for the effort and completed enough to set a standard of quality, then others would join.

The problem is that when you have a culture that doesn’t have an emphasis on writing inline documentation, then few will do so. It is not fun writing inline documentation and is often a lot of work. Also, it would have felt like pushing back the waves of the ocean, so yeah. People can see the benefits and it is easier to continue once most is already documented.

That isn’t to say that it is perfect, people still need to work on the inline documentation, to improve it, to ensure that the documentation doesn’t become outdated from changes of the function, to make sure that undocumented functions are documented soon after and to make sure that future functions are documented before they go in. WordPress may have started with very poor documentation, but it would have been a lot easier to improve the documentation if the decision was made 4 or 5 years ago rather than 1 or 2 years ago. Going foward, it has to be up to every contributor to ensure that WordPress continues to raise to 100% of every function, class, etc be documented and maintain at least 30% LOC to Documentation LOC ratio.

For the project to go from 4% to 8% ratio 31% is nice, very nice. It also took a while to get there. What I benefited from it? I benefited from the experience and knowledge with the ability to write phpdoc docblock style comments without needing to look up what each tag does, what it will look like, and how it is used. It speeds up my ability to write inline documentation and thus I write more of it in my own projects. I’m finding that it wasn’t a waste of time and that it has and will serve me well in the future.

Possibly Related Posts:


Home Entertainment Center Project

Posted by Jacob Santos on November 1, 2009 Comments Off

I’m going to place the TV and other devices on the west wall in the living room, between the doorway to the bathroom and the doorway to the kitchen. This gives me 75″ width and 70″ height to work with. This project is not a short term goal and will probably be within 3 or 4 years. Parts of the project will be completed before other parts, but does require the TV and shelving to be completed.

Goals

The primary goal is to buy the TV, shelves, and sound system. This will be near $3500, so the next stage with buying the gaming systems will be another $1000 or so, not including games.

  • TV that is over 50″, but under $2000. This also has to have at least 3 HDMI connections, but isn’t all that important, because I plan on buying a sound system to plug the HDMI into and then just plug the sound system into the TV for video.
  • Sound System is going to have HDMI connections for sound and video. Doing it this way, I can plug most of the devices that are HDMI into the sound system, have the sound go straight to the sound system and then have the video directly sent to the TV. This will reduce the amount of wires required to complete the devices.

    One of the longer term projects will be to send the speaker wire through the walls to hide them. This can be achieved easily by placing the module with the wire ran underneath the flooring and then back up to where the sound system is located. This will reduce the amount of wiring needed and will look a great deal tidy. The problem is that once this is done, it will be very time consuming to correct, so setting it up without first and then running through the walls is a better choice.

    The sound system is probably going to have either a DVD player or a Blu-Ray player as part of it.

  • Shelves

    The shelving will be glass and I want to have close to about 6 shelves. The bottom shelves are going to be 30″ wide and long enough to hold most devices. I will proably need to place it a foot off of the ground in order to fit the other shelves with the TV. I can only do two shelves on top of each other or I’ll be limited on the screen size. The good news is that I’ll be able to place a shelf mounts on each side of the TV that is 12″ wide for speakers or I could use speaker mounts.

    I might not use glass for the shelves. I think it is fine if it is wood, since it is unlikely to cut and slice the person if they happen to fall through it. The point is to not fall through it, but I’ll rather have the odds that if someone were to fall through it, then they wouldn’t require hospital attention. The reason to have glass is that it will match the rest of the house. Given that I may have kids, I’ll rather be safe than sorry and it will probably be cheaper for wood shelves.

  • Game Systems

    I’m going to buy a Playstation, Nintendo, and whatever system Microsoft has out in 3 years. These will be 3 of the five or six shelves, although, the Nintendo could probably fit on one of the shelf with another game system.

  • TiVo or Internet Connection Device

    In three years, I doubt seriously that I’ll have cable. I’m doing exceptionally fine without cable TV with Netflix, Hulu, etc. The need for cable TV is diminishing, so thus is also the need for TiVo. If I need to, then simply, I could get away with using my computer to record TV and then stream to the Xbox or Playstation devices. I’ll have to wait and see. Most likely after the sound system and game systems, I’ll at least want to have a few shelves open for future devices.

Possibly Related Posts: