Documentation is marketing

One of the most important things any product team builds is the documentation others need to understand and use the product.1

Yes, “the ideal product needs no documentation,” but people look to documentation for a number of reasons. Consider: some a trying to use the product, but many others are trying to determine if the product can do something important to them before attempting to use it. People use documentation for so many reasons that even the ideal product still needs it.

Consider this: 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.

Using Docker on Triton

Triton offers a unique approach to using Docker in the cloud. Documenting the advantages and limitations so prospective customers could make informed choices is a critical part of our strategy (in addition to minimizing differences and making the advantages obvious).

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.

Now, Alexandra White’s screencasts on how to Dockerize an application, scale it with Docker Compose, and use Triton Container Name Service are especially good additions to the docs.

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.

You really should click the links above to see the whole context, but here’s Alexandra’s video on doing blue-green deployments:

Alexandra’s video has helped dispel the complexity many people feel about blue-green deployments.

Developer relations

In addition to documentation and extensive community outreach, successful developer relations requires connecting the product to the tools customers use and depend on. Highlights include:

Beyond our focus on devops productivity, Joyent is also a strong supporter of Node.js. Our guides to Node.js 8 LTS and Node.js 9, and consistent presence at Node conferences exemplify our ongoing leadership there.

Autopilot Pattern developer relations

ContainerPilot and the Autopilot Pattern have been earning a lot of recognition for Joyent, in part because they enable sci-fi-like devops capabilities and because of the great work the team has been doing to demonstrate the pattern using a number of applications:

Documentation at Joyent

I started the practice of trialing documentation as blog posts before adding them to our docs. This partly because our small team is trying to balance creating new value while we restructure docs, and because blog posts give us a chance to get broad feedback that improves the material before we formalize it in our docs.

Documentation at Joyent has had a patchy history, and cleaning the docs into something that preserves the detailed answers in the old material while also revealing the larger product narrative has been a gargantuan cross-organizational effort. Consider these snapshots of our docs over time: 2014, 2015, 2016, 2018. And we’ve been testing this “getting started” page as a replacement front page for the docs: 2017, 2018.

Update 2020: unfortunately, maintaining documentation is also a huge effort, and the docs at Joyent today have regressed from gains made previously (and some content above updated since originally written in 2017).


  1. It should go without mention that documentation is also critical to product development. Well-written documentation and FAQs have the characteristics of good user stories: user, goal, and benefit, in clear language that’s accessible in small, focused chunks. The point of this post, however, is the role of documentation in representing the purpose and benefits of a product. ↩︎