Starting on a new piece of documentation¶
So you’ve been tasked with writing a brand-new piece of documentation. Where should you begin?
A solid first step would be to talk to the experts on the product that you will be documenting (such as the developers, product managers, or project managers) to learn about the product and its expected target audience. Consider questions such as:
- What does the product do? What does it enable users to achieve?
- Is there a particular type of user or business role that this product caters to? If so, what does this user base care about?
Use this knowledge to guide your decisions regarding the type of information that you should focus on in the documentation. These conversations will provide some pointers about the workflows that must be covered, and the product features or technical concepts that you will need to explain. You might also start getting ideas about how to organize and present the information.
For example, if the product is something that has to be installed in order to be used, and you were writing for a system administrator audience, you would probably need to consider a wider variety of installation scenarios or more complex scenarios versus if you were writing for a less technical audience.
As another example, if the product is a GUI application that offers specific ways for users to accomplish each task, you would probably want to write a user guide that walks users through those workflows step-by-step. However, if the product is something like a software development kit with a number of APIs that can be implemented in a multitude of ways, you might want to write a reference guide that describes what each API does and lists them alphabetically so that users can easily locate the information they need.
Understanding the product and the expected user base will guide your decisions on what to write about and how to write about it.
