Pugetworks
Seattle Software Developers

blog-archive

Pugetworks Blog Archive!

Documentation: Is yours useful?

Documentation is the key to helping others understand and use the libraries that we have written. Good documentation should allow someone, with a basic knowledge,  to successfully integrate the library into their project without much effort. Bad documentation can easily remove a useful library from consideration because of difficulty in integration.

I find two styles of documentation; documentation through examples and documentation through concepts. Each style on its own is not very useful, but work as a team to convey a message.

Documentation thru examples

Datatables provides a bit of both styles, but in a disjointed way.

http://www.datatables.net/examples/basic_init/table_sorting.html

On the page referenced above, there is no explanation of what the Initialization Code is doing. If you search long enough, you can eventually find indirect references to the values under aaSorting and aoColumns. But the disconnect between the example and the explanation (imho) puts this site squarely into the 'Documentation thru examples' category.

As with most cases, this library was created to provide a simple way to implement a desired functionality with a certain amount of customization. With enough examples, just about all customizations could be shown, but this becomes onerous and difficult to display to a potential user in an efficient way.

Documentation thru concepts

Most javadocs that I use, seem to fit in this category. One of the main reasons for using a library is to not have to write a piece of code. This could be because it is too complicated or beyond ones ability. To find a library that may do what one wants, but having to basically write a bad version of the library to understand how it works, wastes a lot of time and creates frustration. In some cases, it actually becomes easier to not use the library because some functionality isn't available (or is so buried in the concepts) that the library no longer fits the requirements.

I will admit that I get more use out of provided examples than the concepts. This is probably because I didn't start out in programming. In some cases, it is unavoidable to reference abstract concepts in order to describe the way a library is used.  For instance, when a library is providing functionality from another technology or skill set (example: GIS).

In Conclusion

The documentation should wet the appetite of the potential user and allow them to easily perform the task at hand.  Additionally, it should offer the opportunity to learn the depth of creativeness of the library that has been written.