How to Write a Technical Documentation Plan

There are strong reasons for having a documentation plan. The main one being — setting up a clear and open help authoring process. Creating a documentation plan means giving every team member an exhaustive reference point. The whole team will act within the guidelines of the plan and that ensures consistency and efficiency.

Structure of a Documentation Plan

There’s no strict rule defining how detailed the plan needs to be, but if you really want people to use it, make sure it is well-structured and easy-to-navigate. Do not overwhelm your technical writers — first of all this document should be easy to apply.

How you structure it depends on specifics of your tasks, of course. It can be product-based, role-based, area-based. But there is a certain structure that is preserved in most of the successful documentation plans, we will talk about that in a bit. Also, we will provide you with the tips of what data to include in a documentation plan.

A documentation plan is a bit like a user manual in itself, so you will find a lot of similarities with general technical writing. It should be logically structured. No need to go crazy and create a documentation plan for a documentation plan, but the least you can do is make sure the information is easy to find. For this, use your favorite navigation elements. We recommend using a TOC for sure. Cross-referencing, breadcrumbs, next/previous article links would be great, too, but it initially depends on the format you’ve chosen for the documentation plan. Some tech writers fit all the info inside one long document with a TOC being the primary means of navigation. This might work well for some, but we believe that creating a documentation plan using a help authoring tool just like you would do for any user manual works best. All the functionality like navigation elements is already there and you can apply your own best practices to documentation plan creation.

Content of a Documentation Plan

Since a documentation plan is also a way to align your goals with actions, it all starts with writing the goals and objectives of the project down. They are going to define everything that will be happening further on.

No documentation plan can exist without a thorough content plan. It gives a great bird’s view of the user manual you are set to create. And, maybe, you will get ideas on how to improve it before the production starts. Of course, before starting a project, there are always time frames — this is the next important thing to include.

When we have an understanding of what to do, it is time to mention the responsible people. Make this list detailed if you wish by explicitly describing roles and responsibilities. How these people communicate with each other and outer teams, what the processes are — should be added in the form of a workflow description.

Now, it is time to define the tools and resources your team is going to use in the process. Add a list of software, websites, and services needed to fulfill the task. If you have a separate style guide, you can simply reference it. Or, add a section about design-related things like fonts and font families, colors, page layouts, picture sizes, etc. And, of course, don’t forget to mention what the result of all this work should be. This includes types of outputstheir formats.

Anything you deem important can be included. You can set a desirable readability score for topics, average topic lengths, etc. While the core of a documentation plan should remain static, feel free to work on details if the reality dictates that some things should be added.

Conclusion

Having a documentation plan means standing on solid ground. Your entire team will have amazing reference material which is so helpful for a project of any size.

Documentation plans are extremely helpful when you start something new or before a major iteration of a documentation project. Do you use documentation plans How detailed do you make them? Let us know in the comments below.

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices

Source: https://medium.com/level-up-web/how-to-write-a-technical-documentation-plan-bf4570807f69

Written by

ClickHelp – Professional Online Technical Writing Tool. Check it out: https://clickhelp.com/online-documentation-tool/