Writing your first document

So, you need to write your first document. Where do you start?

Let's look at a hypothetical situation! You've just landed your first technical writing job. You made it through the first few days of onboarding, and now you've received your first assignment... writing a document.

You check the task: it's about how to restart an antenna in case of a GSM error. So, where do you start?

Getting started

Oh boy... so let's get started. First, figure out what you already know:

• You've rebooted a computer before, so you know what restarting something means.
• You've seen antennas around, maybe even studied them in theory at university.
• You might have a vague idea of what GSM is. It's a term you've seen thrown around, but it's probably a bit fuzzy.
• You know what an error is: something unexpected that interrupts normal operation.

Image from Shutterstock

It's not much, but it's a start. You have a rough grasp of the concept. Now it's about getting it out of your head and onto the page, or in this age, onto the screen.

After a brief panic attack, you check what resources are available. Usually, that means a ticket, a design document, some meeting notes, or a mix of all three.

It might come as a surprise, but the most important step comes now. Your job is to teach others how to interact with the concept you are about to write about, but first you have to understand it yourself.

Investigating

If you are a technical writer, chances are you have spent a good chunk of your life warming a school bench. The situation has not changed much. You still need to learn before you can explain. The most important questions to answer, regardless of what you are writing about are the following:

1. What is this new functionality?
2. What problems does it solve?
3. How can the user interact with the new functionality?
4. What can go wrong while interacting with the new functionality?
5. Are there any best practices or recommendations?

If you can answer these questions confidently, you are 80% there already. So, where to begin?

Internal information

Read everything available to you. As I mentioned, these could be in many forms, but the issues are usually the same. Internal documentation tends to be, for lack of a better word, chaotic. It's written as an afterthought, put together quickly after a meeting, created by an expert who skips "obvious" details, or given to someone junior because nobody likes doing it. Language barriers can also creep in. The result is messy at best and misleading at worst.

Nowadays, there are tools at your disposal to make your life easier. LLMs, AI agents can fill in gaps or piece together meaning from half-finished sentences.

I still urge you to first, try to read it on your own. It's an important step. Your main objective is to find out as much as possible about the task and the implementation of the feature. Use this time to try to understand what's really happening. Based on the title or a passing comment, you might think it is only about restarting an antenna, but is the restart automatic or manual? How does the user interact with it? Is there a graphical interface, or is it entirely command line? At this stage, you are playing detective.

Next, read the related documents in the user-facing documentation. While you might only find loosely-related information to your task, it can still give you a basic idea of how already existing terminology is handled throughout the documentation. This not only helps you understand the context in which your feature will fit in, but also provides essential information during the writing process. Make a note of the terms used and try to match everything to the already read internal resources.

More often than not, there is some related API or model available where you can see where related functionalities would fit in. Read these as well, and try to make a mental map of your own.

Gather what you have learned and compare it to your first assumptions. Is anything missing? Probably.

External information

After reading through all available internal information, it's time to check everything external:

• If the feature is tied to a standard such as IEEE, 3GPP, or ETSI in telecommunications, read the standard first.
• If publicly available, look at how other companies do it. No shame in learning from your competitors. They are probably learning from you as well.
• Refresh your related tech knowledge. Learn about antenna restarts. (Re-)read what GSM actually is.
• Check tech forums. Engineers and developers have likely discussed something similar before.

You can use a plethora of tools here, ranging from books and videos, to documentation and forums.

Testing

Is there a demo or staging environment available? While in most cases you might not have a full radio equipment lying around, a simulated test environment of how the user would interact with the feature might be available. If any form of testing is available always use it! It's the best way to learn about a concept. Not only can you identify potential pain points that you should document, but you might understand concepts that were too abstract up until this point.

If testing is not an option, you can still ask people who have access to testing some questions. Unless there is an explicit company policy that restricts access to testing, people are usually happy to give access.

Talking to experts

There are many people working on new functionalities. The reason why I recommend talking to them as the last step of your investigative process because it's rude to take up someone else's work hours. You might be able to get answers more quickly, thus spending less time with the task, but it comes at a cost of someone else's time. Not to mention, by taking less time to understand what you have to write about, the end result will also suffer.

Before reaching out or having a meeting with someone, make sure to formulate your thoughts to remove any ambiguity from your questions. By this time, you probably have a rough draft in your head, which you could share with the person you are about to talk with. It could involve sharing information such as:

• Where you plan to place the new information. Is it a new section in an existing document or an entirely new page?
• If there are templates available, like a template handling restarts, you could share that information as well.
• Walk them through how you plan to structure the new content.

Then, you can ask your questions. You might already know the answers to the most important points, but it's still a good idea to confirm them. Ask who you can turn to with questions, who will review your drafts, and when you can expect feedback. Share a time plan for when you will most likely need further assistance. This helps you avoid potential problems, such as discovering that no one is available during a time-critical stage.

Creating the documentation

After all that preparation and investigation, you finally reach the fun part: the writing. You are a technical writer, not a technical reader, even if you have been doing more reading than writing up to this point. Gather your thoughts, your notes, and your willpower, and start creating the documentation.

Sketching a mindmap

Ask yourself: How will the user interact with this information? Will they read it from start to finish, or just refer to specific sections? The answer will influence your structure, but most documents should include the following:

1. Introduction and summary – Describe the functionality.
2. Prerequisites – Include legal admonitions, safety and brief setup instructions.
3. Instructions – Explain how to use the functionality.
4. Troubleshooting – Outline potential problems and solutions.
5. Best practices and recommendations – Suggest ways to improve performance and avoid common issues.

Writing

First things first: you need a title. A good title is concise yet self-explanatory, which improves both searchability and SEO. You can enhance it with tags, metadata, or other tools. Make sure it reflects how you expect the user to interact with the feature.

For example:

• If the restart is automated but requires initial setup: Set up automated antenna restart in case of GSM errors.
• If the restart is manual: Restart the antenna in case of GSM errors.

Creating the introduction should be straightforward. You have read everything available, so you already have a clear understanding of the feature or functionality. Aim to use simple English, which helps non-native speakers and lowers translation costs.

Avoid overloading the introduction with detail. A single clear sentence can be enough: You can use this functionality to automatically restart the antenna when GSM errors occur during network operation.

Proceed to the prerequisites. Most of these should already be available, so just reuse them. Reuse is the heart of documentation; don't neglect it.

The instructions should be clear, concise, and easily followable in a logical order. You can start with a brief introduction describing what the user must do to use the new functionality, but afterward aim to create a step list with active sentences, like: Add automatedRestart=true to your gsm-operation.conf file.

In the troubleshooting section list common errors, and pitfalls that the user could experience while using the feature, and provide actionable resolutions for them. For example: If the Disconnected antenna error is raised after the initial setup, ensure that the abisErrorDetection is set to true. If the problem persists, contact our tech support at tech@support.amazingcompany.com.

For the best practices part, write any recommendations that can improve performance in specific scenarios. This could be something like: When using the Automated Antenna Restart feature together with Antenna Optimization, enable gsmRestartDetection in the Automated Antenna Optimization window to improve overall uptime.

Congratulations! You just created your first-ever documentation draft. Unfortunately, your work is far from over. Even if by some miracle you managed to avoid making any mistakes there are still mandatory review rounds left to ensure the quality of your work.

The review process

Like many parts of this blog post, the review process could easily deserve its own dedicated article. Depending on your workplace, there may be several different review rounds, including:

• A technical review to ensure technical accuracy.
• A legal review to make sure the material follows local requirements.
• A peer review to get an outside perspective from another technical writer on how the information is structured.
• An editorial review to check that the text flows well and is free from grammar and typographical errors.

All in all, the review process will require some time, so make sure to account for it in your schedule.

Publishing your work

Once your content has passed all reviews, it is time to publish. Double-check that all links lead to the correct destinations, images load correctly, and metadata is in place for searchability. After publishing, keep an eye out for feedback or questions so you can make quick improvements if needed.

Some closing thoughts

This one was quite a doozy to write. There are still many things I have not covered, and as mentioned earlier, each of these sections could easily have its own blog post to explore additional scenarios you might encounter. For now, I hope you enjoyed reading and perhaps learned something along the way. Good luck with your writing!