diagram docops general

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.

There are two ways to get the latest draft of Codewriting, the book:

  • Clone the source repo in Git and build the PDF and HTML. If you have the common prerequisites (Ruby and Bundler), it’s as easy as:

    $ git clone [email protected]:briandominick/codewriting.git
    $ cd codewriting
    $ bundle install
    $ bundle exec liquidoc -c _configs/build-global.yml

    Detailed instructions in the README.

  • If you are just feeling lazy, download the latest compiled PDF or check out the latest HTML draft.