ryanwold.net - Civic Tech, Bitcoin, and Open Government Innovation

Title

Text

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](https://docs.google.com/presentation/d/11hs2Zpq6APCyTRICH1JfPTQfRR8tAon15AtTczGuM4I/edit?usp=sharing), in Draft

An entry