The biggest question when creating documentation and content is who is the end user. Think of the end user as this mystic being that you know is there but may never interact with. I know, a crazy way to think of it, but it is true. Much of the documents/content we create will reach users that were never intended. Think of the last time you found some information that was way too technical or did not provide any background/context. It is obvious that the information was not intended for you but for someone with a more intimate knowledge of that subject. However, you still ended up finding the information and trying to use it for your purpose. This is the challenge of creating content and determining who the end user will be.
The first step is to look at who the intended audience is. This can be an executive, developer, your supervisor, and so on. Once this is determined, think about who could this content also go to. Maybe the information was intended for a developer but was then forwarded to the CFO for budget approval. If strictly created for the developer, the content will be difficult for the CFO to get a full grasp of the information without a Subject Matter Expert (SME) to translate. This could result in a project not being approved solely because of miscommunication. Along these lines is also cultural considerations for teams that are spanned across the globe. Word choices and cultural considerations will affect how the content is created, displayed, and understood.
So how do we solve this? Understand the project cycle and/or work environment. If management must always review/approve technical content being created, ensure the content is both technical for developer use while containing context to the technical information to get non-tech people up to speed. This can be accomplished by utilizing appendices for highly technical content, and the main body has a mixture of both technical and informational content. As mentioned earlier, we will also need to take in any culture considerations within the work environment. Certain phrases or content layouts may have different rates of success when it comes to understanding the information created. The best way to handle this is to work closely with teammates from those areas and receive review feedback on the content you are creating.
Next we look at how the content will be transmitted. Is the information sitting on a sharing platform, printed manual, help system, etc.? All of these mediums could change how the content is created. If the content is commands for a developer, a Quick Reference Guide (QRG) one pager will be appropriate as they may print it out to have on their desk. A help system would need to have both highly technical information filled in with introductory information as not only SMEs will access the information, but also professionals wearing multiple hats. Technical writers will know the request of being the writer, and the QA engineer, and the code debugger, etc.
The last portion is where the content is housed. Will this be on a public facing site for the world to access or on a limited access subnet within a Virtual Private Cloud (VPC). Information for the world, especially help or do it yourself (DIY) type information, will be less technical heavy so users can understand and troubleshoot any issues. Items in a company’s secured database could be based on the types of user access to that content (i.e., dev area is highly technical; more introductory information for average user access; and slides with bulleted information for leadership).
User analysis is a difficult part of content creation to nail down. We know who the information should go to; however, it usually will end up in someone else’s hands. There is no way to consider all possibilities, but we can make educated determinations based on the environment the content was created in and how the information will be transmitted.
Let us know your thoughts or suggestions.