WtD Prague: Docs for startups

This week I’m attending Write the Docs Prague. It’s super exciting to attend a European Write the Docs conference, and to be visiting the lovely city of Prague. This post contains my notes from a talk at the conference. All credit goes to the presenter, any mistakes are my own.

Brian Lemke’s talk was “How to launch your startup with good docs”.

Brian talked about what he found when he joined a startup as a tech writer. The team had started creating the product, hired a marketing team, and scheduled the release date. They had not started the docs. How can a tech writer handle this situation?

Key contact people

Tech writers need to talk to certain people to get the docs created. Brian mentioned two key roles in a startup.

The startup developer is highly innovative, wants to build something new, and wants to avoid bureaucracy and hassle. Their prior experience is that docs are part of the “hassle” of software development. Startup developers also often lack experience in working with a team that includes a tech writer. They want to focus on the code. They want the doc process to be easy.

The product person is also creative, innovative, and knowledgeable. They usually do have prior experience in docs. The task of creating the docs often falls on the product person, and often that happens rather late in the release cycle. They know they need the docs to communicate the product within and outside the company. They want the developers to contribute to the docs, and they want a way to make that process easy.

You need to build a doc system that works for everyone. But how?

Principles

Help the team understand the following key principles:

Docs are part of the product. Docs are not a byproduct of the code. The docs should be a core feature, and not something that just appears when you run a script against the code.
Docs must be on the roadmap. The docs must be released with the product, and must get special attention with respect to milestones and outputs.

Brian spoke about working in an agile environment. The doc tasks should be part of the team’s “feature epics” so that the docs are planned along with the other tasks.

Executing the plan – docs as code

Brian recommends following the processes of “docs as code” – a philosophy that you should create the docs using the same tools as the developers use for the code. This gives the developers a sense of ownership of the processes and tools, and makes it easy for them to contribute to the docs.

At the startup, Brian’s system involved GitHub for the code and docs, Swagger for API docs generation, and Hugo as a static site generator for publishing the doc site.

Put the developers in charge of creating and implementing the docs system. This will increase their sense of ownership.

Obstacles

In the startup world, there are many competing priorities and the team is generally smaller than in an established organization. You may need to fight to keep docs as a priority.

Startups are also prone to “the pivot”: a sudden change in direction for the startup. Brian says, don’t panic and don’t lose hope. The infrastructure of a good docs system won’t change when a pivot happens. In fact, a good docs infrastructure will make it easier to survive the pivot. The developers will be comfortable with the tools and will know how to update the docs when the pivot happens.

Thanks Brian for a glimpse into the world of startup docs.