Enter … docs as code!ĭocs as code is a philosophy of writing documentation with the same tooling and practices as writing code, from each developer’s preferred text editor to a version-controlled publishing sequence with pull requests, build previews, and even automated testing.
USE GITBOOK EDITOR ON GITHUB UPDATE
More than updating our tooling, we needed to update our whole approach to take the next step in documenting the Baseten platform. In all, this was too much friction for small changes and not enough flexibility for large ones. From there, changes went live instantly, unless they chose to use GitBook’s review tool. Previously, for an engineer to contribute docs for the first time, they had to get a GitBook account set up, then use the web interface to draft docs. While our existing system had a lot going for it - the simple web interface had enabled our team to publish thousands of words of customer-facing documentation covering key features - I realized that there was a big opportunity to improve the experience for engineers. I need to write large chunks of documentation, review other peoples’ changes, get my own changes reviewed, and establish internal workflows and documentation for technical writing. Your friendly neighborhood technical writer (me!), who owns the docs site and related outcomes.Designers, who ensure that the docs have consistent branding and style with the rest of our sites.Marketers, who need to be able to make updates without relying on technical workflows.Engineers, who want to use familiar tools that minimize the friction of writing documentation.I started by taking a step back to understand the needs of all four groups of stakeholders: When I joined Baseten, our documentation was hosted on GitBook, but there was discussion of switching to another solution. While I was hired to help our docs keep pace with the rapid iteration of our product, in order to provide truly best-in-class docs for a technical audience, we need to directly include the engineers in creating the documentation. Every enhancement and new feature shipped gives docs a chance to fall behind.
While a blog post is a one-time commitment that can be scheduled out and easily prioritized relative to other work, documentation must grow and evolve alongside the product. Baseten has a long-running project to support every team member in writing and publishing a blog post on a topic of their choosing, from photo restoration to parental leave. When I joined Baseten as a technical writer in January 2022, I was impressed by how much high-quality writing a small company had managed to produce while working heads-down on building an ambitious product.
0 kommentar(er)
