One of the most import things any product team builds is the documentation others need to be able to use the product.
Yes, “the ideal product needs no documentation,” but people use documentation for so many reasons, and they come to the product from so many different points of view, that even the ideal product does still need documentation.
Besides that, documentation is marketing, documentation is where you show your customers and prospects not only how to use your product, but how to think about it.
Documentation at Joyent has had a patchy history, but Alexandra White’s work to build new content has reorganize the backlog has been a bright spot.
Using Docker on Triton
Triton offered a unique approach to using Docker in the cloud. Documenting this was a top priority from 2015-2017.
The formal docs are here, including a comparison of Docker CLI with Triton CLI commands and task-oriented docs for common tasks like starting containers.
Here’s her screencast on using Docker Compose:
Using Packer and Terraform on Triton
Packer and Terraform provide a rich set of tools to manage VMs and other cloud resources, and they also offered some workarounds to limitations in Triton, but the easiest way to get started using any new tool is usually by watching somebody else. That’s why Alexandra’s screencasts about these tools are so valuable.
- Create customer images with Packer
- Deploy applications with Terraform
- Automate blue-green deploys with Terraform
You really should click the links above to see the whole context, but here’s Alexandra’s blue-green video:
Blue-green deployments are a complicated thing for many people to understand, so that video has been especially helpful to a number of users.
Documentation at Joyent
At Joyent we typically use blog posts to trial run items before adding them to our docs. This is in part because of the complexity of Joyent’s history of documentation, and in part because blog posts give us a chance to get broad feedback that improves the material before we formalize it in our docs.
Alexandra spoke about some of the challenges of documentation at Joyent, as well as her process for developing a plan to improve the docs at Write The Docs 2018 in Prague: