While writing up the draft docs for Joyent’s Container Name Service I leaned heavily on the user stories and use-cases for the feature. It has me realizing that we should consider user stories to be the first draft of the user documentation.
Indeed, consider that well-written docs and user stories have similar qualities: a user, goal, and benefit, in clear language that’s accessible in small, focused chunks.
The CNS docs are now in our core documentation library, and I’m happy that we’ve updated the content management system to support deep linking to individual headings, like this one about adding CNS service tags when creating an instance with the triton CLI.
I’m thinking about this and writing now because Alexandra has joined the team and is adding short screencasts that do more to “show, don’t tell” how to use the features while providing additional context. See this screencast explaining usage with docker, assigning vanity names, and her overview of CNS’ function and purpose. She’s been digging in to the existing documentation, asking questions, and driving a lot of improvements. All that had me considering the source material and the relationship to user stories.