Crafting Documentation with Purpose

Jul 11, 2021
4 min read

Updated: Jan 28

From system design to user manuals,

clear communication is key

Network Solution Department

You have created a variety of documentation, haven't you?

Yes. In our work, we broadly refer to it as "documentation creation," but it actually covers a wide range of materials, like requirements documents, various design specifications, test specifications, Standard Operating Procedures (SOPs), progress charts, and operation manuals.

For hardware-related documentation, we always check the latest versions from each manufacturer and revise them to meet the specific needs of each project.

We make sure that in urgent situations, everyone can easily locate the correct documentation so there is no confusion about where to find it or what it means.

That makes sense. In an emergency, it would be a serious problem if work were delayed because the necessary documentation couldn't be located. Keeping all information up to date is essential, but I imagine it must involve a lot of effort.

That's true. But in fact, "creating documentation" is also about "defining clear guidelines." This documentation outlines the scope of responsibilities, actions, and tasks for each team or group, and it clearly specifies the procedures that should be followed. In other words, it ensures that everyone is working under the same set of rules and using a common language.

Additionally, some of this documentation can serve as supplemental materials in contracts, providing a reference or even legal evidence if any issues arise.

I see. So every word really has to be chosen carefully. That's a big responsibility.

Please tell us about the steps involved in creating documentation.

In many cases, we base the documentation format on what the client is already using, but we adjust it as needed to make it more user-friendly. Having a well-organized collection of past documentation is very important, as it often serves as valuable reference.

List all necessary items (and confirm the overall direction with my supervisor)
Review the applicable template rules
Prepare materials in advance for information sharing (especially important when multiple team members are involved)
Create the full documentation
Submit it for review (by supervisors, team members, clients, etc.)
Revise the documentation based on feedback
Finalize the documentation

I see. It sounds like the preparation stage at the beginning is especially important.

Do you have any tips for creating effective documentation?

First of all, it's essential to confirm the overall direction with your supervisor during the initial outlining stage. This step can save a lot of trouble later on.

Next, make sure your template maintains consistency throughout the documentation. This includes standardizing chapter titles, body text formatting (such as font style and size, the use of formal or plain language, punctuation, etc.)

Finally, clearly defining all terminology used in the documentation helps prevent misunderstandings, inconsistencies, and reduce the need for rework later.

If you let someone else directly edit your documentation, unexpected formatting problems can occur. For example, in Excel, page breaks might shift unintentionally, and these small invisible changes can cause problems in the final version. One useful technique is to always make corrections yourself in your master file when receiving instructions for revisions.

For certain documentation, such as Standard Operating Procedures and test specifications, it's important to check from the end-user's perspective whether any criteria, such as how to judge whether a task is successful, are clear and unambiguous.

That was very insightful!

Are there any other challenges you face when creating documents?

It depends on the type of documentation, but one thing that is common across all of them is that you need to tailor the content to the intended users. This might include information needed by specialists, clients, engineers, or even the manufacturers. Each group requires different information, so the same topic must often be presented in different ways.

For example, manuals prepared for clients who are familiar with IT may use completely different vocabulary from those intended for clients who are not. It's also important to choose the most effective delivery method, whether printed material, digital formats such as PDFs, or even videos, based on what users find easiest to understand.

In this sense, creating documentation isn't just about technical knowledge and writing skills, it also requires a deep understanding of the user's perspective.

I heard that you also handle tasks beyond documentation.

That's right. I'm also involved in implementation work, pre-implementation verification, and summarizing the results of those verifications.

Even for projects I'm not directly assigned to, I still create Standard Operating Procedures and test specifications. To ensure the documents are as accurate as possible, I take part in the actual verification process myself.

Hearing that you actually work on the tasks yourself while improving the quality of the documentation really shows your dedication as a professional.

How have your contributions been received by stakeholders?

Actually, I always try to submit documentation ahead of the specified deadlines so that reviewers have enough time to check it carefully. It's really motivating when I'm praised for the speed and quality of my work. I have also received positive feedback on our team's strong internal review processes.

Thank you very much! It's really impressive to see professionals who put so much care into creating reliable documents, especially those that matter in critical situations.