Atomic Documentation

Atomicity is the property of some texts where component portions of the text are written as independent and self-contained chunks that combine to form a complete documentation resources. Such approaches require modifications to how texts are constructed and the kinds of tooling we use, to support document creation, publication, and output.

Advantages of Atomic Documentation

  • Documents are easier to maintain, because sections of text can be reused and referenced. When something changes, it only needs to changed in one place.
  • Documentation is easier to write. Atomic approaches turn otherwise huge projects into parts that are easier to write, because rather than construct an entire technical narrative, one need only describe specific functions, operations, and concepts at any point.
  • Structures and organizations can be created and manipulated outside (above) of the text itself. Atoms can be reused (theoretically) in multiple contexts as needed.
  • (others?)

Disadvantages of Atomic Documentation

  • Documentation may be conceptually more complex to organize and manage.
  • Tooling for publishing and authoring atomically constructed documentation must be more complex and specialized.
  • There may be a slightly higher barrier to entry for contributing to documentation.
  • (others?)