Documentation is Code is Documentation

Writing Documentation for and with Developers

author:Sam Kleinman
company:10gen, Inc.
project:MongoDB
link:http://tychoish.net/oh-2012/

Preamble

Documentation Engineering

Documentation Triad

  • How it works.
  • How to use it.
  • What's possible.

Documentation at 10gen

  • Kernel Team
  • Driver Team
  • Integration Team

... and more.

MongoDB Documentation Circa September 2011

Legacy Documentation

... and a lot of it.

Limited Processes

No formal conventions for:

  • Reporting issues.
  • Capturing changes.
  • Release processes.
  • Collaboration.

Unsustainable

Maintenance and Collaboration

How do we:

Evolving Needs

MongoDB Grows

  • New users every day.
  • New features every day.

Usage and Abusage

  • Documentation must address user support.
  • Limited body of existing patterns and procedures.

Solutions

Tooling Matters

General

  • Reproduceable offline builds.
  • Accessible for editing and contribution.
  • No "expensive" tasks that can't be automated.

Other Requirements

  • "Edit this Page" button.
  • Branched versioning.

Process Matters More

Diffusion of Responsibility

State of the Art

Tools

Process

Open Questions

Postamble

Credits

Open Discussion