What constitutes "good" (software) documentation?

Software ocumentation is a sticky issue and tends to escalate rather quickly in opinion matches, fighting over what is needed, what is missing and what should be different.

Looking at it closer I see 3 main dimentions:

• audience
• content
• format

Each documentation artefact has a sweet spot in this cube as well as no-go zones (e.g. a business user watching a live coding recording?).

Any individual can and will fit into one or more audience, as each artefact will fit into one or more content categories. So good navigation and cross references are essential

Audience

Audiences for documentation range from novice coders to senior business decision makers (think CxO), so documentation needs to be clear, whom it is catering to and how it gets delivered. A good index by audience can thus add tremendous value. Lets have a look:

• Business Users: Vision statement, Use cases / Case studies (preferable with ROI), End-user How To, Release Notes
• IT Leadership: Use cases, dependencies, security, integration, architecture
• IT Operation: Deployment (with all sub-items as above), dependencies, release notes
• Support: Reference, How To, security, release notes
• Development: Source code documentation. NO: there is no such thing as self documenting code. Well written clean code can tell the how, but hardly the why. Architectural decisions, especially roads not taken and agreed coding convention

Content and Format

Key for content and format is discoverability, relevance, referencability and ease of maintainance. The further documentation is away from production, the more likely it is out of sync with the application. What works quite well is to keep documentation in a repository close to the product, eventually as close as the source code's /docs folder (if you publish your sources), to enable the same eyes to gaze at both product and documentation sources.

Documentation gets read magnitudes more often than it gets updated. It is made accessible for search by JavaScript blind search engines. So static files and good old SEO beat fancy PWA any time. The exception here are interactive reference components like OpenAPI UI or Design Systems like Storybook.

Video / Audio should always come with a transcript, so impatient or time-limited users can skimp through the parts that are relevant for them. A good cross-reference, well curated boost the utility of any material.

How-Tos can span from short, task specific instructions, delivered static or as video, up to full courses, in this century delivered online. I quite liked the approach used by the OData tutorial, taking advantage of PostMan

Pitfalls

It is a hallmark for a good novel to jump into action instead of lengthily introduce the actors. However the novel's delight is the documentations nightmare. You rather want to introduce scope and expected proficiency as well as references when proficiency needs an upgrade.

The worlds engineering documentation is written in DITA, so the best approach would be to use that as the general format? Not so fast. DITA is the perfect format to create complex, cross-referenced documents with a focus on "single source of truth". A term, once defined, can be pulled in anywhere, so you never risk having e.g. security procedures out of sync.

However it is a specialized format, that, without proper tooling, is a nightmare to maintain and requires specialized knowledge. This precludes community contributions. For software a more practical approach are markdown files and a page generator like GitHub Pages, once you have a nice template. Maven Site does a reasonable job using mvn site. The site structure is given by meta data in the file and the file location. While this is limited compared to DITA, it lowers the bar, so documentation pull request, internal or external, become viable.

As usual: YMMV