CHAPTER 2 Writing Maintainable, Future-Friendly Code
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^10 , a large amount contributed by a passionate community. Fur-
thermore, 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.
Twitter Bootstrap^11 is another library that benefits from excellent
documentation. When you arrive at the site, you’re met with a lot of infor-
mation about how to get started. All of the patterns are documented with
code and live examples so you can see exactly what you’d get by applying
certain classes to HTML. The popularity of Bootstrap is owed in part to the
simplicity of getting started, and that is because of the high-quality docu-
mentation.
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 soft-
ware 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.10 http://docs.jquery.com
11 http://twitter.github.io/bootstrap/