Skip to content

Latest commit

 

History

History
126 lines (72 loc) · 2.94 KB

presentation.adoc

File metadata and controls

126 lines (72 loc) · 2.94 KB

An Introduction to Docs-as-Code

by Sean Marquez

Frequent concerns with managing documentation

  • What were the changes/design decisions

  • When were the changes/decisions made

  • Who made the changes/decisions

  • Where were the changes/decisions specified

  • How were the changes/decisions implemented

  • Why were the changes/decisions implemented

Characteristics of modern software development

  • Changes to codebase are captured in a "commit history"

    i.e., who changed what & when

  • Workflow conventions often incorporate an issue tracker

    i.e., where they were specified

  • Workflow conventions often include discussion & review process

    i.e., how & why a change was implemented

What is a Docs as Code approach?

Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code.

Advantages to a Docs as Code approach

  • Writers integrate better with development teams

  • Developers will often write a first draft of documentation

  • You can block merging of new features if they don’t include documentation, which incentivizes developers to write about features while they are fresh

To adopt a Docs as Code approach, consider the following…​

  • Language

  • Toolchain

  • Methodology

Language

  • Markup language used to write the docs

    e.g., Markdown, ReStructuredText, Asciidoc, LaTex

  • Template language, a superset of a markup language, used to format the docs

    e.g., Liquid, Jinja2, Handlebars

  • Source language of the toolchain used to render the docs

    e.g., Ruby for Asciidoctor, Python for Sphinx

Toolchain

  • Issue Tracker

    e.g., Jira, GitHub, GitLab

  • Conversion Engine / Static Site Generator

    e.g., Sphynx, Asciidoctor, Hugo

  • Distributed version control system

    e.g., git

  • CI/CD service & publishing platform

    e.g., TravisCI, GitHub Actions | GitHub Pages, ReadTheDocs, Netlify
    Some publishing platforms have CI/CD services built-in

Methodology

  • Docs-Driven-Development

    Write your docs first, then implement what you documented

  • Agile Development Practice

    e.g., scrum, kanban

  • Code (Docs) Reviews

    Have someone review your docs (e.g., as a pull request on GitHub)

Example Projects that use a Docs-as-Code Approach

  • NodeJS

    https://github.com/nodejs/nodejs.org

  • SoCal Linux Expo A/V Team

    https://github.com/socallinuxexpo/scale-av-web/

  • This presentation!

    https://github.com/capsulecorplab/docs-as-code

Closing thoughts…​

With a sufficient number of users of an API, it does not matter what you promise in the contract; All observable behaviors of your system will be depended on by somebody. - Hyrum’s Law

The End