At my current place of employment, a lot of emphasis is placed on who the audience is for our technical content. Are our readers developers? Are they IT Professionals? Are the consumers? A lot of time and energy is spent creating these silos where writers can focus on their audience and what their audience wants in the hopes of pleasing them by offering the right content. There are usually writers in place that specialize in types of content directed toward these roles.
Right now my day job group has organized one division’s writers into teams based upon what their audience role is. There’s a group writing “developer documents”, a group writing “consumer content”, etc. But often a product needs content from a mix of these arbitrary teams to provide good coverage. Many products need to tell developers how to write for or in that product but also need to tell OEMs how to distribute or customize it and may need to tell users how to use it. Right now this means that there are different people in different teams trying to work on different aspects of documentation for one product. They have to go through a lot of gyrations to work together and are often prevented from actively helping each other because of some idea that a person working on one team cannot possibly do work on some other documentation aspect.
Some products blur the lines between roles a lot, too. That only adds to the chaos. Who is in charge of x documentation when x is sorta developer but sorta IT Pro? How is a decision made? Who makes it? When?
The minute we start focusing on the roles instead of what the user is trying to accomplish, we have made a mistake.
Most users don’t actually care what you call their role. The role label is pretty arbitrary, it leads to a lot of assumptions and isn’t at all consistent across just my company, let alone other companies.
Users care about getting their job done. That’s it. They use content as a way to find out whatever they need in order to get their job done. I’ve yet to meet a single user of documentation that I’ve worked on that asks about content based on role. They want to write an application that uses a particular API. They want to get updates to a product and install them. They want to use the product to produce a document. These are all tasks – does it matter whether the job title of the person trying to accomplish the task is “developer” or “chief dishwasher”? No – the task and how to accomplish it remains the same.
But if you start by saying you are producing developer documents, you stop looking at the tasks and instead start asking yourself what a developer cares about and probably narrowing your focus more than you should. Just because a person is a developer doesn’t mean they only ever write code to use APIs. If you segregate your documentation by role, you put the onus on your audience to try to find where you hid the documentation on a task they need to perform.
Heck, I’ve personally had to download Software Development Kit (SDK) help files to look up something I need to do that is only documented in that SDK help but I’m not doing development. This can lead to a long game of “where’s the cheese” which only frustrates your users and can sometimes make them try some other product.
Whenever I get into a heated discussion about this topic, the very first thing out of their mouths tends to be questions about sample code or sample applications. Of course there’s a place for those — in a section of the documentation that is focused on the task of, say, developing applications that work with or on the product.
I start with categories of tasks, then tasks within those categories. What is my user trying to do? That is the first question I constantly ask myself. If I can create an excellent, easy to follow, task-based structure to my documentation, it doesn’t really matter what role my audience is.
