Modern technical writing - Andrew Etter 2016
Define the audience
Basics
Writers have to make assumptions in order to achieve anything useful. Bare minimum, we assume that people can read2. Similarly, you should assume that your readers know how to use a trackpad and won't freeze up when the Enter key reads Return. Assuming anything less leads to writing like this:
Place your hand on the mouse and, moving your hand (and arm, as necessary), direct the white cursor on your monitor. If your monitor is not on, you can turn it on by pressing and releasing the power button. The power button icon can be found in Appendix D: Icons. If your mouse has multiple buttons, press and release the leftmost one. If your mouse has one or fewer buttons, press and release either the only button, or the left section of the mouse, respectively. If you are using a trackpad...
A colleague once argued to me that you sometimes have to target your writing to just such an audience. The proper response to such an assertion is to let your eyes bulge out of their sockets and shake your head from side to side, but if you must reply, the simple counter-argument is this: you cannot help people who require that level of hand-holding. They probably won't read the documentation, and even if they do, they definitely won't understand it. There's nothing you can do for them. Better to say:
The Settings menu lets you adjust mouse sensitivity and button mappings.
This statement involves a lot of assumptions. We're assuming the reader can find the menu, knows what mouse sensitivity is, and can infer that some button behaviors are customizable. We're also assuming the reader knows the basics of manipulating a computer and has the application open. I'm happy to make all of these assumptions, regardless of audience. If an application has a lot of button groups and only a few are customizable, you might need to be more specific, but the level of detail is basically fine. Don't get stuck in the quagmire of trying to help the helpless. I know it sounds cold and mean-spirited, because these are the readers most in need of assistance, but by catering to them, you are doing a real disservice to the other 90% of the population.
Now that we've defined who is not the audience, we can roughly divide readers into three groups: users, administrators, and developers.
Users are people who just want to achieve something with an application, whether it's resizing an image, creating a spreadsheet, or sending an email. Users are typically concerned with inputs and outputs. They type a few things, drag a couple boxes around, and voila, a monstrosity of a PowerPoint presentation is born.
Note
A user interface is not a requirement for someone to be a user. Command line applications have users, too, people who just want to copy and paste some common commands and move on with their lives rather than mastering the syntax, chaining commands, and incorporating regular expressions.
Administrators install and configure applications. I'm not just talking about server administrators or people with administrator permissions on a computer, but anyone whose concerns are setup and maintenance. How much disk space does the application server fill over time? Where are the logs located? How do you recover data in the event of a crash? What's the simplest way to perform backups? How do you troubleshoot poor performance? In consumer applications, the user is often also the administrator. In business applications, this situation is less common.
Developers extend applications or interfaces with code. They want to improve some aspect of an existing application or build something new. More than anything, they need reference materials, short tutorials, and code samples. Conceptual introductions to a language or framework are wonderful, and if you have the time and expertise, by all means, write them. But programmers check online language and library references hundreds and hundreds of times. They only read Programming Python once. If you have to prioritize, go with the former. Most modern designers fall into the developer group, as well.
Knowing which group an audience falls into gives you a reasonable starting point, but you still need to home in on actual use cases in order to focus the documentation. A single inaccurate assumption about your audience can lead to a mountain of discarded work. Take the time to truly understand what your audience wants to accomplish through conversations, meetings, interviews, analytics—anything at your disposal.