Skip to content

Warning

work in progress

Docs as code at Forma.ai

Benefits of docs as code

We were using Bookstack

Alternatives

Docusaurus

Most of our devs work on the backend.

They may not know React

We also don't need a single page app.

Goals of docs

  • [ ] integrate into codebase and engineering workflow
    • [ ] for engineering docs
  • [ ] Decrease the fragmentation of the docs
  • [ ] Get feedback from users about the docs
    • [ ] drift: how in sync are the docs with the code
    • [ ] did you find what you were looking for?
    • [ ] 👍 or 👎
    • [ ] how many views does each page get?
  • [ ] User documentation
    • [ ] Commissions Analysts
    • [ ] Sales Reps
    • [ ] Financial Business partners
    • [ ] HelpJuice?
  • [ ] Find an alternative to diagrams.net to create diagrams
    • [ ] inside the markdown?
    • [ ] excalidraw
    • [ ] mermaid
    • [ ] diagrams
    • [ ]

Documentation quality audit

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

  • Issue Trackers
  • Version Control (Git)
  • Plain Text Markup (Markdown, reStructuredText, Asciidoc)
  • Code Reviews
  • Automated Tests

Notes on docs tech talks

Google: How Two Technical Writers Changed Google Engineering Culture

https://www.youtube.com/watch?v=EnB8GtPuauw

  • g3docs
  • enable engineers to find, create and maintain docs
    • keep docs in a simple, portable format (Markdown)
    • next to its associated code
    • rendering it at a logical URL
  • Why people don't like docs
    • they don't exist
    • they're hard to find
    • they're wrong
  • Why don't people write docs
    • no time
    • no incentive
    • no culture

Twitter: Creating the culture of documentation

https://www.youtube.com/watch?v=6y4eQ6gYwdU

  • platform (DocBird)
    • Twitter use Sphinx
    • implementation of ReadTheDocs
  • Templates
    • enforce consistency
  • DocDay (community)

Build Docs like Code (CI for docs)

https://www.youtube.com/watch?v=wEt_8twQctQ

  • more layers of separation/time between implementation and writing the docs
    • more inaccurate docs
  • devs dislike the workflow of writing docs
    • have to switch tools
    • gets pushed off
  • treat docs like code
    • docs are stored in git
    • build doc artifacts (website) automatically
    • trusted set of reviewers to review docs
    • docs are tested
      • content accurate?
      • do the links work
  • what we gain
    • promotes collaboration
    • tracks doc mistakes as bugs
    • include docs in code review
    • beautiful, uniform docs
  • versioning docs
  • types of docs
    • long form docs
      • user guides
      • getting started, FAQs
    • Functional docs
      • REST APIs
      • SDKs
      • man pages
  • mkdocs

Writing Great docs (by a maintainer of Django docs)

https://www.youtube.com/watch?v=z3fRu9pkuXE

  • docs are communication
  • why do people read docs
    • great docs serve multiple conflicting users
      • need to document things multiple times
    • new users
    • education
    • support
    • troubleshooting (annoyed users)
    • learning internals (devs)
    • reference
  • who should write docs
    • great developers (the person who wrote the feature)
      • Django requires that new patches come with new docs
      • the person who just wrote the code knows about it the most
      • write something and get feedback
      • wiki is where good docs go to die
      • wiki tells me that you don't really care about your docs
  • what should we document?
    • Tutorials
      • quick (new user should feel a win within 30 mins)
      • easy but not too easy
      • show off how the project feels
    • Topic Guides
      • Conceptual
        • tutorials are about parroting
        • topic guides: kick them out of the nest
      • Comprehensive
        • tell the WHY of the topic
    • Reference
      • complete
      • for experienced users
      • HOW of the topic
      • Igor doesn't like auto-generated reference
    • Troubleshooting
      • answers to questions asked in anger
      • FAQ need to be frequently asked
  • which tools should we use?
    • tools don't matter (but use good ones)
    • Sphinx
    • Docco and Pycco

Spotify: How we're solving internal technical docs

https://youtu.be/uFGCaZmA6d4

3rd biggest blocker: not being able to find the the info you need

Challenges (that are solved by docs as code)

Highlight to open a GitHub issue

MLP: Minimum lovable product

Vision: Spotifiers using tech docs go from stuck to unstuck in less than 1 minute

https://backstage.io/blog/2020/09/08/announcing-tech-docs


Last update: 2022-11-04