DIY Documentation

Published: 5 August 2007 | 7 comments

In a Godbit interview with Leslie Camacho, VP of EllisLab, the company behind the popular CMS ExpressionEngine and the open source PHP framework CodeIgniter, Nathan Smith asked the question, “Do you have a team of in-house writers documenting your products, or is that all done by developers?”. To which Leslie responded, “It’s all done by the developers and myself.” That’s DIY Documentation right there.

I thought that was rather interesting. Having never written formal documentation for a framework or application, my only interaction with the process was reading ones already written by someone else. I had no idea how difficult or easy it was to write. I’m currently working on a project and looking back at what I’ve done so far, I realise that despite leaving little comments here and there, I think I could have done a better job documenting the code and also write some documentation for the user (I mean the application seems pretty straight forward to use but you never know). Surely that’s not a good thing and I feel a little bad now for not doing a better job of that from the get go.

Now if you have used or heard of CodeIgniter/ExpressionEngine, you’ll know they both have some pretty darn good documentation and even their code is well documented also. Derek had the following to add in response to Nathan’s question:

We feel that forcing developers to write documentation yields better code, better docs, and a better application/framework. Writing about how you do something often changes your perspective in a positive way. If it’s too complicated to write in plain English then chances are something needs to be improved in the code, interface, and/or the functionality. That’s not always true, but its a good starting point.

Usually the development team writes the initial drafts of the docs and then I go through and polish things up, add screencaps, and so on. We take our docs very seriously and will even delay release if the docs aren’t just right. Several “doc hounds” live in our community and sniff out every single error we miss. We do our best to correct those as quickly as possible.

Now I’m no expert, but this just seems to make a lot of sense to me and I thought to myself, “Man, it would have been good to have heard this when I first started on that project.” We learn something new every day and I guess from here on I’ll be making more of an effort to write better documentation.

Permalink

Comments

gravatar Ben — 6 August 2007

When I was a CSS major (a two years I am thankful for now, but wasn’t enjoying at the time), the pushed documentation really hard, so we did a lot of it.

gravatar Matt — 6 August 2007

That’s pretty impressive that EllisLab developers write their own documentation. I would call it a best practice since no one knows the code like the person coded it.

Unfortunately, in the IT world documentation is typically an after thought that is poorly written. I never liked documenting my code though I would make comments to my self if something was a bit unusual. Helps out when bugs appear later on.

Putting comments in the code itself was always pushed in the CIS department of my college. They always pointed out that you might know what the code does but someone else coming in a few years later to either update, fix, or utilize your code would have a hard time without some comments.

I think Ruby on Rails has some neat documentation features. It can basically compile the code comments and other useful info from within the code itself to create a fancy reference manual.

gravatar Derek Allard — 7 August 2007

Yup, and in addition to the docs, take a read through the code. It is clean, consistent and thoroughly commented. A fine piece of engineering indeed!

We also recently announced user contributed userguide notes, and coding standards (http://expressionengine.com/docs/development/guidelines/index.html)

gravatar Yannick (Author) — 7 August 2007

Matt: Yeah true, most times it’s an after thought. I think I fell into that trap with my project.

Regarding RoR compiling the code comments, correct me if I’m wrong but Java and PHP can do that too. Java has JavaDoc and PHP has PHPDocumentor. Were you referring to something else?

Derek: Thanks very much for pointing me to the EE Coding Standards, that’s pretty neat and I’m sure will be helpful if I do any EE/CI plugins.

gravatar Matt — 9 August 2007

Yannick: I was unaware of JavaDoc and PHPDocumentor but I’m not surprised they can compile the comments as well. One neat thing about Rdoc is that is can still produce fairly good documentation even if the source code contains no comments.

Does JavaDoc and PHPDocumentor have the ability to compile all methods and classes used in your code into a single page and provide info about each?

I’ve found a page that is fairly similar (definitely not the same) to what RDoc produces. Hopefully, this will better explain what I’m trying to say.

gravatar Yannick (Author) — 9 August 2007

Matt: I do believe both can do the same as you have described of RDoc. I’ve yet to try it though, but I do intend to, as I try to improve the documentation of my source code.

gravatar Matt — 10 August 2007

Yannick: Sounds good…I learn something new everyday.

Comments have been disabled on this article.