Skip to content
Olivier CarrèreTechnical writing practice

KISS: keeping technical documentation simple

Concept
Technical writingContent reuse

How the KISS principle applies to technical documentation: information architecture, DITA content reuse, and sentence-level writing that stays maintainable.

, 2 min read

View as Markdown

Keep documentation as simple as possible without making it less useful.

What KISS means for documentation

Section titled “What KISS means for documentation”

The KISS principle is a general engineering rule: anything people build is more reliable, and easier to maintain and extend, when its complexity is kept deliberately low.

Applied to technical documentation, it is a design constraint rather than a writing style: whatever the format, a writer can produce a cleanly structured document set or a Rube Goldberg machine, and the difference shows up years later in what it costs to change.

Why simplicity matters

Section titled “Why simplicity matters”
  • Comprehension. The reader spends their effort on the product, not on your structure.
  • Cognitive load. Fewer cross-references and detours to hold in mind at once.
  • Maintenance. The structure you choose now sets the cost of every later change.
  • Fewer failure points. Every reuse link, override and exception can break silently.
  • Change. The product will evolve; simple structures survive it, elaborate ones are abandoned.

KISS in practice

Section titled “KISS in practice”
Information architecture
One obvious place for each TopicThe smallest autonomous, titled unit of information in DITA XML, typed as concept, task, or reference and assembled into documents via ditamaps.View in glossary →, and no hierarchy the reader has to decode.
DITA and content reuse
Reuse what is genuinely identical. Every ConrefA DITA XML mechanism for reusing a block of content by reference: the content of a target node is replaced by the content of a source node at compile time.View in glossary → is a dependency you agree to maintain.
Authoring
Few styles and no overrides; let the format carry the structure.
Writing
One idea per sentence, in the order the reader acts.
Maintenance
Prefer a structure you can update in one place without tracing what else it feeds.

The classic failures: conrefs centralized or nested too deeply in DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary →, described in too complex a document architecture?, and in FrameMaker, styles and overrides multiplying until nobody can manage the document.

Before and after

Section titled “Before and after”

A procedure written by someone who had not yet understood it:

In the event that the user wishes to modify the configuration parameters, it is recommended that the service should first be stopped, subsequent to which the configuration file may be edited.

The same instruction, once they had:

Stop the service before editing the configuration file.

KISS is not about writing down to the reader. It is about removing the complexity that costs the reader effort without giving anything back.

Where the technical writer adds value

Section titled “Where the technical writer adds value”

A simple sentence is harder to write than a complicated one, because it requires understanding the material first - which is exactly why testing the product is worth the time.

The judgement is what the role is paid for: deciding what can be simplified and what complexity is genuinely part of the product, where reuse saves work and where it only creates dependencies, and which structures will still be maintainable after three releases.

Where the idea comes from

Section titled “Where the idea comes from”

The principle was decisive in the design of the Swatch, whose specifications called for half as many parts as a comparable watch: cheaper, more reliable, and easy to reissue endlessly. The Shadocks - the absurd birds of the cult French cartoon - put the opposite case just as memorably: Why keep it simple when you can keep it complicated?

Section titled “Related articles”
Section titled “Related reading”