Technical content

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 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.

We write documentation so that what we create is 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 helps 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 has specific expectations and context when reading your docs.

Some examples of possible audiences and their expectations:

• External users
  • Have very little context
  • May need more information
• Developers
  • 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 are they reading? To accomplish a task? To learn about the project?
• Does 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 give you a better idea of how to present your information. Then you get a good idea of how to structure your document.