Documenting Large-Scale and Complex Products

To advance your technical writing career, you may want to start documenting exciting, complex-to-use, large-scale, and market-leading products. However, at this scale, the development velocity is fast, demands are high, and the task is daunting. Technical writers should be aware of prioritization, information architecture, content strategy when dealing with especially complex product documentation. In addition, they should understand the nuances of negotiating with management for extra resources, team dynamics, and the basics of delegation. Understanding these aspects is beneficial when you’re tackling a big and complex documentation project, on your own, or as a part of a team.

Key takeaways

• Information architecture is basically three things: documentation structure, the user experience of documentation, and discoverability of information.
• The documentation structure should always follow and guide the user’s journey. A user journey is a set of steps on a high-level that the user is supposed to perform, when they interact with your product. There is no high-level all-encompassing user journey under developer tools which are supposed to help users debug everything on the web. Instead, they have a collection of pieces of workflows, and web developers integrate these pieces into their overall workflow. It’s fine to organize these things at a high-level if it follows the natural flow of information discovery.
• The Eisenhower Howard Matrix is a well-known prioritization framework. It has two dimensions: urgency and importance. If a task is important and urgent, that means you should do it right away. If it’s important but not urgent, you should schedule it. If it’s not important, but urgent, you should delegate. If there is backlog of tasks logged into a bug tracker and not being prioritized into other three categories, it will end up in the red category. The red category means that at some point in time, the task becomes outdated and not needed.
• Before delegation, the first thing you need to do is set up a progress vector, which basically means three things. Explain the current situation, paint a picture of a perfect world, and outline your current plan on how to get there. And while you’re doing that, don’t forget to welcome ideas on how to improve the plan from your direct reports. Second, make your expectations clear. Third one, provide mentorship in its basic form. It means that you should regularly ask what the pain points, how you can help, what resources you can provide to make things better.
• Only delegate the tasks that you know how to do. And there are two reasons for it. First, it’s a bad idea to teach people how to swim by dropping them into the water without support. Second, if you know how to do the task, you’ll be able to efficiently review the result in no time.