First off, thanks to Niall for this great idea! I was looking for something to write about and he recommended a "documentation template" for new features.
I'm going to make more of a checklist than a template, but I think the end state is similar. These are things to consider and questions to answer when putting together docs!
What are the pre-requisites?
I love this quote. I wish I knew where Dan got it from.
@cpojer Someone said “assume zero knowledge but infinite intelligence” and I’ve found this guideline helpful.19:42 PM - 20 Jan 2020
It's something to live by if you're a teacher/educator. And it's something to remember as a developer documenting the stuff you've built.
However, when it comes to documentation I'd add a caveat. Assuming zero knowledge is not always practical, so as an alternative, communicate your assumptions. That means asking yourself a few questions and attempting to answer as objectively as possible!
It's quite easy to get "too close" to the thing you've built that you forget how little others know about it.
What does this document assume your user already knows?
Since this is a new feature, it likely exists within a larger ecosystem. Your explanation for how to set up and use the feature is going to use terms and concepts a brand new user might not know! Explain what those are upfront, or where to read about them.
A good example is a new API endpoint doc. That likely assumes the user is familiar with the API itself. Provide some links or quick narrative text to cover these bases with the reader. They may need to do some additional reading before starting on this new information.
What does this feature require your user already have setup/working?
While the previous question is a bit more fungible, this one is not. What do you have to set up on your computer in order to work with this feature?
There are so many potential gotchas here, but these are a few things to consider:
- Does this assume a working project that already exists?
- Does the user need an account somewhere?
- Does this require a key or secret of some type?
- Do they have to download anything?
- Do they have to configure anything?
- Do they need to have data of a specific type or stored in a specific place?
- Are there other dependencies you're assuming they've installed?
Note that the answer to the previous question is sort of input for this one. If you've documented your assumptions and sent users to other write-ups first, there are granular details you don't have to include here.
A good example is downloading Node.js. If your base assumption is that the user is set up to work with the API already and the docs for doing so include Node.js as a requirement, you can exclude that here. Just be sure that you've communicated that expectation.
What does this feature do?
Explaining what your new feature does is one of the most important things documentation does. When a user scans your documentation they should have a chance to understand what they'll be setting up if they follow your instructions. The goal is that they can decide ahead of time whether they want to.
A quick narrative explanation is usually sufficient. If an example link or screenshot is appropriate that's great too!
How do I set it up?
This is the bread and butter of your documentation for a new feature. Assume nothing. This is brand new to users even if you've been developing it for months. Even if it's been in beta!
A step by step guide for doing so is best. Something like:
- Install X
- Configure Y
- Create Z file in P location
Are there other options or flags?
Your main example will likely be the happy path. Keep it un-opinionated so it applies to the most number of use cases. That being said, don't forget about all the other options.
Are there other settings? Flags? Alternative configurations? Other API parameters?
If there are, document them here! One of my favorite options is to include a table of the options along with data type and description. The Gatsby blog theme README has a good example.
How do I use it?
Don't forget this part! I can't tell you how often documentation includes set up instructions for something new and then stops short of example usage.
It may seem obvious to you, especially if this is functionality that other systems have - but I can promise it isn't to your user.
Just today I came across a situation like this and opened a PR in Gatsby.
Some rules of thumb:
- Include code snippets where applicable.
- Make sure to specify where they should live, e.g. what file.
- Include necessary imports in your example.
- Show varying examples if you can! Recognizing patterns helps people.
Example Links
It's great to show one example up top when you're explaining a feature, but feel free to add more at the bottom of your doc. Some people prefer to look at things in action rather than read about them. It may improve adoption!
Feedback
Add a link for feedback if relevant. Whether it's filing GitHub issues or contacting support, it's great to have early adopters (and late ones) helping you fine-tune your feature!
Next steps
This is an optional add on but it's something I've always enjoyed. Call out other related or sequential features in your tech! Share links to those docs. You'd be surprised how often that helps people find what they're "really" looking for.
Top comments (4)
Thank you so much for this blog post! I really appreciate you walking us step by step through your process. I am thinking about tech writing as a career path because I really believe that good docs make tech more accessible and your writing is definitely one of the reference points for me ❤️
Excellent! Thanks for sharing this. I'll be saving it in my recommend links for interns.
Great article! Thanks for writing it!
In the "Example Links" section, did you mean links to "live" examples like codesansbox, for instance?
That’s certainly an option. But other repos using the feature, sites using it, etc are all valid.