What if documentation could be fully integrated with the product, from source repository to end-user delivery?
This site is both an experiment in, as well as living instruction of, an emerging system for collaborative documentation developed in environments where docs are effectively code.
docs sourced under the same version control regime as product code
canonical product info, with a single source of truth informing the backend, user interfaces, and all docs (internal & user-facing)
developer tooling and infrastructure available to documentarians — Git, IDEs, testing, automation
dynamic content processing such as conditional flows & variable substitution in the docs
modularity — mix and match docs source to meet the specific needs of product version, audience, and so forth
docs packaged and delivered in the same flow as code, output in all the right places at exactly the right time
lean docs drafted/generated throughout the dev process, from API to GUI
Codewriting is a website and a book, each drawn from the same open source codebase and sharing some of the same content. The project exemplifies the AJYL docstack, a set of integrated technologies perfectly suited for demanding, collaborative technical documentation projects.
|AJYL stands for AsciiDoc, JAMstack, YAML, and Liquid. For more, see the companion website about AJYL dockstack.|
The content source is written in a lightweight markup language called AsciiDoc, supported by small data files in YAML format. The codebase is managed and processed by several awesome utilities, including Git, Asciidoctor, Jekyll, and my own tool, LiquiDoc.
And it is all available to anyone who finds it helpful. No strings attached, though I’d love to hear from you.
Codewriting’s mission is to expose what I’ve learned and help others acquire the skills to establish, maintain, and use great docs-as-code environments. It is time for tech writers to become codewriters. At its essence, codewriting is docs hacking.
You do not have to be a developer to take advantage of this system, which you can derive lessons from a la carte. That said, if you are not yet a developer, this might be a great first step toward becoming one.