Forewarning: I’m not an expert on this subject, however I do play one on television.

Software engineering is mostly a solitary, and technical occupation. Most of the non-programming language communication made by a developer is communicated to another person with domain, contextual, and similar technical knowledge. Very rarely, information is communicated to someone outside of the domain, or contextual atmosphere, let alone technical knowledge. This guide is more of a collection tips and reasons to document that I’ve discovered over the years.

  1. Acknowledge your audience. For frameworks, nothing is more frustrating to the reader when a quickstart guide is written for existing developers of that framework. Those developers do not want a quickstart guide, they want the Java/Net-doc. I’m looking at you Spring. If your audience is technical and new to your framework, please identify concepts that are exercised within the framework. Preferably, as an appendix and referenced to at the introduction of the book/document.

  2. Proof-read the document, even better: Have someone, even better people, from the targeted audience proof read the document for accuracy and readability. It is unbelievably surprising to discover how difficult it is to write documents that deal with troubleshooting, installation, configuration, or documentation of “common tasks.” From my experience, just the modification of an existing code base to add a new report took 4-5 pages of bullet point instructions. Once a documentation guide is published errors/incorrect documentation is embarrassing, are difficult to correct, and can be very costly.

  3. Screenshots: Screenshots make describing tasks involving a GUI clearer.

  4. Pictures [more than screenshots]: Reading words are useful, however a simple diagram is often useful for explaining complex architectures, or tasks. It also includes people who are visual learners.

  5. Versioning the document: This helps the user identify the document’s “up-to-date-ness.” I really hate advising this, as that some documents begin to include the change list. [Who really cares about this? All I want to know, as a reader, is if I have the most current version]

  6. If you are documenting source code and haven’t written by the time that you get to the unit test. Write the documentation while the tests are being written. If the documentation has already been written, write the unit tests based on that, even if you have access to the source code. From my experience this can piss off the original developer. However, as a tester, you should depend on the resources given to you, not what the actual structure is. From my experience, this level of pedantry can piss off the original developer, but in the long run it may prevent major errors in future reuse of the code. Make the unit test break if the documentation isn’t followed!!

  7. Provide documentation! Your developers/designers/user’s are very intelligent, however being intelligent does not make one a mind reader. Don’t expect another person to understand your [or your team’s] motivation, history, design decisions, or politics surrounding the project.

  8. Allow for feedback. If there is mistake in the documentation, provide the user to contact the author of the documentation for confirmation of a mistake. If you don’t do this, expect for people to be pissed off about your API, idea, project, source code, or product.

  9. Document bugs or deprecation: If something doesn’t work or is going to be removed. Warn the developer.  It’s better to know beforehand.

  10. Support: Support is more than a scripted technical support call. If you have better documentation low level support calls can be eliminated or substantially lessened. Additionally, supporting the documentation/product can give insight to the functionality used in the product and/or bugs that were previously not found.

  11. Job Security: It may sound contradicting (Most people I’ve talked to claim that obfuscation keeps a person employed for a while, at the expense of others), however it’s hard to claim that a person isn’t doing the job they were tasked with, or deny a promotion if their procedures are sufficiently documented.

  12. Documentation can help you identify architectural and interaction [GUI, and API] issues. This is more of a case of an problem, previously unrealized, coming into the consciousness. You’ve identified the issue, now you can talk about it and come up with a solution.

  13. For APIs: Provide examples for every method. Write a paragraph on: why someone should use that method, why one shouldn’t use it, the performance and memory costs, and the state change to the operation of the software or environment.

Have tips for technical writing, documentation? Leave them in the comments! [See I even provided feedback for this post :P]