Skip to main content

Posts

Showing posts from July, 2017

An alternative, better approach for writing technical documentation

Technical documentation for a software project is a complex topic. I've seen all sorts of approaches throughout the years and implemented many of them myself. I've seen everything from a "no documentation found here" approach to using a Wiki to hundreds upon hundreds of pages in a PDF (or other specialized format like CHM) that no one really reads. In addition, technical documentation almost never mirrors reality. The source code is always the definitive authority on what happens. Technical documentation is mostly an afterthought, "Oh, yeah, I guess I better document that thing I wrote."

Most users of software can't be bothered to read the source code OR the source code is proprietary and only available in binary form or remote means (e.g. a REST API). Users want something more human-readable than source code to look at anyway even if the source code is definitive and, in many cases, more readable than the technical documentation.

First I want t…