Model-view-docs: taming large-scale documentation projects using structured data¶
Description
Solid documentation almost always involves skillfully wordsmithed narrative text. But in the contemporary software landscape, narrative text increasingly—yet not always comfortably—lives alongside information generated from structured data formats like JSON and YAML. This includes REST API docs, command-line tool docs, supported platform matrices, and much more.
In this talk, I’ll argue that using structured data can make docs, especially for highly multi-faceted software projects, more robust, informative, navigable, and maintainable. I’ll first present a more theoretical argument in favor of re-conceptualizing documentation in terms of what I call the “model” layer and the “view” layer. This will set the stage for the centerpiece of the talk, which will be a walk-through of an information portal for a fictional database that includes docs for a a CLI tool, client SDKs, a REST API, numerous configurable parameters, and a bevy of tricky core concepts.
- Conference: Write the Docs Portland
- Year: 2020
