These guidelines exist to help you create content. Not to point out problems or make you feel bad for not meeting some standard.
The idea is to free you from having to worry about details so you can create helpful documentation. Instead of spending time agonizing over April 1 vs. 1 April, you can focus on writing something people will read and use.
If you find the guidelines too constraining or you’re missing guidance on something particular, let us know! Kiwis can reach us at #plz-documentation.
Why write docs
We write documentation so that what we create will actually be used.
For your project to be used, people have to know:
- Why it exists
- How get it set up
- How to use it
Docs represent an ideal way to get people to understand why and how to use what you’re building.
One thing to keep in mind is that the person who may need to know how your project works could be you in six months. After you leave a project, you might not remember all of the decisions you made and why you made them. Having clear documentation will help make sure you don’t lose your valuable insights to time.
It’s always important to keep in mind who you’re writing for. Each reader will have specific expectations and context when reading your docs.
Some examples of possible audiences and their expectations:
- External users
- Will have very little context
- May need more information
- Probably want technical information
- Might not know the details of this specific project
- Project managers
- Probably don’t want much technical information
- Might be browsing for understanding the concept
These are just examples and might not be universal. Before you start writing, you want to ask yourself questions about your readers such as:
- Are they new to this project area? Do they have experience with it?
- Why will they be reading? To accomplish a task? To learn about the project?
- Will this document come in the middle of something they’re in a hurry to finish? How are they likely to be feeling when starting to read?
The answers to these questions will give you a better idea of how to present your information. You’ll have a good idea of how to structure your document.