Documenting Smart in the Age of Agile

Technical Documentation has long been something developers tend to ignore, and Project Managers typically defer whenever anything threatens to delay releasing a product or a new feature. With the advent of Agile and its valuing “working software over comprehensive documentation”, documentation has too often been treated as a low priority if not an optional facet of a project. With the advent of automated tools such as Javadoc, the perception has been that the code is essentially self-documenting, even without adding documentation-specific comments. Nothing could be further from the truth, especially when it comes to APIs and Web services.

APIs and Web services exist so other users can access your content and functionality. If those users can’t figure out how to implement a particular scenario or solve their real-world problems, they’ll go to your competitors – and possibly post negative comments about your API or Web service on tech blogs and social media. When you think about it, it’s not so much about creating comprehensive documentation as it is about leveraging the concepts of clean code, automated documentation tools, and the right kind of documentation comments. The goal is always to make it as easy as possible to read, understand, and utilize the API or Web service and any related sample code, thus reducing the time it takes to become comfortable and productive with it. And that includes your support personnel.

The concepts of clean code, with respect to documentation, is all about naming and consistency. Choosing the right names can greatly reduce the amount of documentation you have to write, as well as make you code and API or Web service more readable. Being consistent can be as simple as having all methods that require a start date accept the same date format(s) and have it in the same position in their signatures.  Since the concepts of clean code would be an entire blog all by itself, do read Clean Code – A Handbook of Agile Software Craftmanship by Robert C. Martin, published by Prentice Hall – specifically the chapter on naming.

Automated documentation tools catalog. While they can tell you what, they cannot tell you why or how – they merely identify and organize your classes, interfaces, templates, constants, data members, methods, method parameters, return values, and so forth – something that would take forever to create manually and be a nightmare to maintain. While most IDEs can generate and access this information in real time and present it as fill-in options while coding, a catalog will not:

• Detail any interrelationships or dependencies – if any – such as sequencing of function calls or which members of an object argument are referenced, required, or modified.
• Indicate permissible values for data members, function arguments, and return codes, such as whether:
  • a particular object argument – or return value – can be NULL, and what that means.
  • a NULL string or array is treated the same as an “empty” string or array.
  • particular numeric values, such as zero or a negative value, have special meanings.
• Explain why you’re doing what you’re doing – something you probably won’t remember six months from now and a new team member can’t learn if you leave the team.

You must provide this information through the right kind of documentation comments that focus on why and how:

• Package-level comments that provide a summary and overview of the package, and typically include design patterns for using the classes and their methods, specifically how they sequence.
• Documentation comments (/** … */) that describe classes, their data members, methods and parameters, and so forth.
• Single-line comments (//) that are visible only to those that have access to the source code.

With documentation increasingly being written by the developers who are writing the code, the technical writer typically supports the development effort by looking at the “big picture” and promoting consistency and coherency, so it’s wise to bring them in as early as possible, and certainly not after all the decisions have been made. This in turn enhances usability, improves reliability, reduces support requirements, and facilitates ongoing development.

Package-level comments typically exist outside of the code, but are still part of the project. The technical writer often assumes responsibility for this aspect of the documentation.

Documentation comments focus on why something exists, its permissible values and what they mean, possible error scenarios and how to recover from them, and so forth. They ignore aspects handled by the automated documentation tools, such as type, value limitations of a particular type, exceptions thrown, and so forth. And there’s no reason why a technical writer can’t write the documentation comments and merge them into the code – or at least edit what the developers have written. Some of the best discussions on how to create documentation comments can be found in The Elements of Java Style published by Cambridge University Press, and specifically the chapters related to documentation. Similar books for C^# and C⁺⁺ are available from the same publisher.

Single-line comments should only be necessary in the case of:

• describing how a complex algorithm has been implemented
• coding around compiler or 3^rd party API/library bugs or other shortcomings (if they are your APIs/libraries, you should fix them!)
• identifying code that can/should be optimized or otherwise improved, such as a catch block.

“Standard” comments – those the start with /* and end with */ – should only be used to temporarily hide code. Don’t confuse “standard” comments with documentation comments, and don’t use single-line comments (//) to comment out code!

And remember – whenever you change the code, be sure to evaluate whether you also have to change the documentation comments. While bug fixes usually result in minimal changes (if any), enhancements often affect both the package-level comments and the documentation comments:

”When the code and the comments disagree, both are probably wrong”

– Norm Schryder