A civic-minded citizen seeking the singularity

An entry

Ambient Documentation

Date: 2015-02-07
Status: release
Tags: ambient-documentation

I've noticed that many agile developers and designers shirk Documentation. Perhaps the term has developed a bad reputation from waterfall-era "Requirement Docs" that would originate far from where the products were built, and the communication throughout the process was uni-directional and sparse.

Documentation can evolve, as well.

I believe Documentation should be inherently linked and resonant for a project. For example, Documentation can represent a 1:1, very literal description of its operations, function, UI, etc. (screenshots, API docs, RDocs).

Then, there are lower-resolution, derivative perspectives of a codebase that should resonate. I like think of it as Ambient documentation. You just kinda get it for free. (Railroady, Auto_Screenshot). A visual UML diagram omits lots of information, but it can help to convey a complex domain model at a glance. Visual documentation is a greater abstraction than literal documentation.

In Railroady's case, code is written to inspect code, to generate documentation. The value of this Documentation (like a Data Model Diagram) is that it provides another perspective from which to view, share, and iterate upon. This type of documentation is a projected generated by analyzing a codebase.

I think Programmers (and especially very good ones), often underestimate the amount of brainpower and imagination they are employing when translating thousands of written lines of code, likely, in at least 2 languages, with knowledge of handfuls of libraries, behaviors, into a working mental model. How much of this mental model is shareable? Especially when it takes complete working knowledge of the system to develop a working mental model.

Also, I have Slides, in Draft