There is a lot of good information in the latest Write the Docs newsletter - https://us6.campaign-archive.com/?e=d900d0ff92&u=94377ea46d8b176a11a325d03&id=b5cd1d9248 - but I wanted to not forget the following two topics:
Addressing the user as “you”
This month’s discussions included the question of whether it’s OK to directly address the reader in the second person (as “you”) in technical documentation. Sometimes “you” isn’t quite right. For example, in API docs, it may be more accurate to talk about what “the application” does rather than the actions a user might take. Or you may not need to address the user at all, for example when you’re describing default settings: “The default setting for $Property is 10.” In other cases, your company style guidelines or docs stakeholders’ opinions may discourage or even prohibit the second person. However, most people said they use “you” without reservation in documentation. Using “you” can make sentences easier to read, impart a more conversational tone, and help avoid passive voice. And it’s not without institutional support: Microsoft recommends using “you” in documentation, as do many other companies – for a list of many examples, see Daniel D. Beck’s The second person is OK in developer documentation (but don’t take my word for it).
Dealing with the myth that people don’t read docs
We’ve all heard it - the idea that documentation doesn’t really matter, because nobody reads it anyway. And if you’re reading this newsletter, you’ve probably got a strong feeling that it isn’t true. But how do you refute the idea when people bring it up? The Write the Docs Slack community had some great ideas on this, ranging from the serious to the lighthearted. On the immediately useful end, you can point people to docs site analytics, or to community surveys (such as those run by GitHub or DigitalOcean). These give you immediate data to show the myth isn’t true. Asking colleauges which user studies they have been carrying out that suggests that people don’t read the docs will at least give you time to think of another answer. You can also highlight that people ‘read docs when they need to, not for fun’, or indeed mention the value of clarification inherent in the docs process even if those docs don’t get read. On the less serious side, you can try deleting the docs and letting the person asking the question field the support tickets. Or “just” make the product good enough that it doesn’t need docs. And finally, as ever, it always depends. How much users actually read and use the docs will depend on what kind of product you have, and what kind of docs you have, among other factors.
No comments:
Post a Comment