Some internal rumination that I thought would make a nice blog post.  Stuff we’ve learned after a dozen years of dealing with startup software documentation.

Because most software is a moving target, the vast majority of end user documentation is out-of-date soon after it is created.  Out-of-date documentation is worse than no documentation because it adds to, rather than detracts from, confusion.  This problem becomes exponentially worse when maintaining documentation across multiple languages.  It can become a nightmare when resources are limited.

To help prevent the documentation from turning into a problem, consider the following heuristics:

• Only create a piece of documentation when there is a real need.  Never create documentation for features that are intuitive.  When in doubt, leave it out.
• A picture is worth a thousand words.  Use screenshots and a minimal amount of text.
• Avoid full-screen screenshots.  “Narrow” screenshots are easier to understand and much easier to maintain as the software evolves.  That said, leave enough surrounding space so that the user can recognize context.  (A screenshot of, for example, a single widget is like trying to ask someone to make an identification from a picture of an eyeball..)
• When possible, describe a feature in general terms rather than specific steps.  This approach will have more “staying power”, meaning that the documentation is less likely to change even if there are small changes to the software.
• Create a style guide to help keep the documentation consistent.  Especially important when multiple people are working on the documentation.
• If resources are limited, only translate “proven” documentation or documentation that is demand.  Services like Freshdesk have “Was this answer helpful?” features.  I recommend only translating documentation that gets at least one up vote, or issues for which we get at least two support requests.

And of course:

• Whenever possible refactor for usability rather than write even a line of documentation!

If you’re working on documentation and have come across this post, I feel for ya..  Keeping the scope as small as possible will bear you in good stead.