The goal of this series is to cover some essential concepts and best practices for app documentation. Check out Part I here.
Get to know your audience
You probably got the key facts about your users' needs and abilities when you started your project. Don’t forget these needs and abilities when you write your documentation! You’ll need to consider things like:
- what terms are they familiar with?
- what assumptions can I make about their knowledge?
- what do they really need to know? (hint: not your entire thought process when you made it, but how they should use it)
- how often will they use this app?
- which features will they use most frequently?
- Are different users using it in different ways? (hint: identify clearly which parts are useful to which users)
Level up your writing skills
It may (or may not) sound easy to write documentation, but in fact it takes training and practice for most people to write technical documents that are both useful and usable.
One way to build this skill is to take a short course focusing on writing skills. Google offers a free course in Technical Writing aimed at developers. Another great resource is Write the Docs, where you’ll find plenty of resources for building skills and selecting tools.
Even if you don't feel great about writing, focus on structure. When your document is structured logically, and each part is clearly marked, your reader can skim to look for what they need.
Some tips based on our experience:
- Start from an outline and then fill it in
- Begin each section by telling its purpose
- Write descriptive headings
- Use subheadings for longer documents
- Write short sentences and paragraphs
- Use simple words and sentence structure
- Use bullets and numbered lists where appropriate
Bonus points: Read it again and edit (or ask a teammate) – improve clarity and remove extra or repeated information. Sometimes, what seemed crystal clear when you wrote it is not so clear the next day, or week (even to you).
Make it part of your development process
Over time, we have learned that it’s important to always deliver software products with documentation. Here are a few tips we find helpful to “build in” documentation in smaller stages along the way. That way you can avoid rushing through it at the end.
- Include documentation in the development process (include it in your “definition of done”).
- Set aside development time specifically for writing and editing documentation.
- Outline the sections that need to be written as you go, fill in details whenever you have time.
- Create a template that specifies what needs to be covered in documentation for any project – you can reuse it whether you are a team of one or many.
- Update your docs when you update your app – both for your team and for your user.
- Include docs in your AIMMS project folder, to keep it in sight and in mind.
