The purpose of documentation is to help the user understand the tool they're using and overcome any blockers preventing them from reaching their goal.
The Octopus Deploy documentation lives at octopus.com/docs, and is stored in the GitHub repo.
Before continuing with this page, you should make sure you've read our other writing guidelines, in particular:
How to structure content
You should structure documentation as follows:
- Introduction.
Provide an introduction that explains what the documentation covers and provide some sample scenarios that highlight the main use cases for the feature being documented.
Note: Edge cases should be included in the reference/advance use cases section at the end. Avoid adding edge cases to the main body of the text as they can confuse people about the intended purpose of the feature.
2. Procedural.
Next, provide the information the user needs to successfully use the feature. Where ever possible, break the procedure into simple step-by-step instructions to make it as easy as possible for the user to follow:
- Select Projects from the main navigation in the Octopus Web Portal, and click ADD PROJECT.
- Give the project a name that's meaningful to you and anybody else who'll work on the project.
- ...
3. Additional information
Next, provide any reference material, advanced uses cases or edges, troubleshooting steps, and FAQs.
Reference material
Tables provide an easy way for users to scan lists parameters of parameters for the ones they need. If the reference material is extensive, add it to a child page and link to it.
If there are common troubleshooting steps users might need to perform, list them here.
4. Learn more
Add links to related documentation, the blog, or other resources to help the reader continue their journey.
Adding a new page vs. editing an old page
As a rule of thumb, we should aspire to make each explain something that will help the reader achieve a goal.
In some scenarios, there might be multiple options and including them all on a single page might give the reader scroll fatigue or make it difficult to jump between the pieces they need. In such cases, it might be better to include the options on child pages.