User Documentation Checklists If this is the first piece of documentation you're writing, please try to think about structure. Structure is extremely important to ensure users can easily find what they're looking for. You can have the greatest documentation ever, if you don't pair that with a good information structure your users might as well become frustrated as if you didn't have any. Here are some good links on how to build a good information structure for your docs: You can also get some inspiration by taking a look at some good product documentations out there: Make sure you are being objective. You need to maintain readers interested and help them find what they need with ease. Think about your formatting, it's extremely important! For example, look at how this small change makes the text look much more intelligible: BAD: GOOD: Think about the product feature's use cases. List them out and make sure all cases are there. Having hands-on experience is a huge help, so try all flows out in your system. After that, focus on writing the consequences of each case and their actions. Ensure you are explaining (relevant) things thoroughly and don't take things for granted. Please keep in mind that you, as a developer or technical writer, are biased. Reflect about the language you want to use. If your audience is technical, get technical. If your audience is non-technical, don't use technical terms unless needed (and even so, explain them!) and think about what really matters to the reader. As an extension of the previous topic, make sure you are using language that your reader is accustomed with. If you find yourself trying to explain a flow that would become extensive like this: First access the menu by clicking at the gear icon, then navigate to View my profile. After that just click it might be better to include a GIF recording of the flow along with the text. Images are underestimated. Humans are visual beings and inserting a picture or a recording of your product along with its textual counterpart will make users better understand what you're meaning to say. Try to have another person look at your documentation to ensure everything looks good. If it's a good practice to have PR reviews, it's also a good practice to have Documentation reviews! If you can, run some documentation testing by asking regular people to read your docs and try to use the feature you're writing docs for. Watch them using the product and don't interfere. Observe and write down what they had trouble with and ask them about it in the end. This way you'll be able to identify blind spots in your documentation. Sources:
