Importance of Documentation

Documentation is the part of the job that developers like the least, yet it is frequently just as important as the code itself.

If you look at the success of any major open-source software, you can usually draw a straight line between that success and the presence of excellent documentation. jQuery owes much of its success to the excellent documentation that surrounds the library, a large amount contributed by a passionate community.

Furthermore, other jQuery users set up their own blogs with tips and tricks, and tutorials abound. That was even before jQuery books started popping up. These days you can do a quick search for anything related to jQuery and find hundreds of examples and tutorials.

There’s a reason why popular open-source software asks for and spends time on contributions to its documentation: if software is hard to use or too opaque, then people won’t bother with it. Yet the same developers who regularly complain about some software’s lack of documentation are the same people who look for excuses to not write documentation for their
own software.

Good software is well-documented software, and bad software has little documentation. There is no such thing as maintainable code that isn’t also documented.

Even the most horribly written software becomes more manageable when there’s documentation. The documentation lifts the veil of magic around the code and allows developers to work more effectively with it.

That’s why no piece of software should be considered complete without accompanying documentation. Writing good documentation isn’t hard, it’s just a matter of transferring your thoughts into text and images. Depending on the type of software you’re building, it may make sense to structure your documentation in different ways.

Documentation Generators

API documentation is the minimum that a project should have for documentation. Most languages, including JavaScript and CSS, have tools for generating documentation from the source code. These documentation generators use comments embedded within the code to create standalone documentation (typically in HTML format) describing the code. The exact comment style depends on the tool being used.

  •  JSDoc: the original JavaScript documentation generator. It uses JavaDoc-style comments to create API documentation.
  • YUIDoc: a JavaScript documentation generator from the YUI team. It also uses JavaDoc-style comments to create API documentation.
  • KSS: a CSS style guide generator. Extracts comments inside of CSS, SCSS or Less files and generates a style guide with example output.

There are documentation generators for almost any language you would use to build a Web application.

There is no such thing as too much documentation for code, but there is such a thing as too little. The best way to encourage documentation writing is to make it part of the feature deliverable. A feature should not be considered complete until adequate documentation is written and placed in the appropriate location.

Leave a Reply

Your email address will not be published. Required fields are marked *