The process for creating documentation varies across different spaces. Creating documentation for an open source project where there might be a lot of hands working on the documentation would differ in ways, both minor and major, from documentation created in-house for a company product where you might be the only one handling the documentation.
The expectations might also differ depending on your background, say you have a background in software engineering or you don’t have one and you are pretty much just a technical writer.
In this article, we would look into the process of creating documentation for companies when working in-house as a technical writer. In a future article, we would cover the process of working on open-source documentation from scratch.
We are covering both of them in separate articles because there are nuances specific to each of them and it would be best to explore these nuances in an article dedicated to each of them.
That said, let’s get into the details.
5 Steps for Creating a Good Documentation
Working in-house to create documentation from scratch, it is important to know first the resources and people available to you to create the documentation.
By resources, we mean source materials, stashes of documents (READMEs, product design documents e.t.c.), inline code documentation, and product demos, which might not necessarily be organized, that contain useful details on the product you want to document.
By people, we mean the contacts within the company available for consultation on the product. They are very important in helping you gain a rich understanding of the product you are documenting, and also in gaining a broader context in the form of the company’s mission or vision, customer demands, and so on, as it relates to the product you are documenting.
It is important you identify these people within your organization and develop good relationships and communication with them. This will be key to helping you work with them in order to help you gather the information you require for your documentation tasks.
It is expected you have done these foundation tasks or groundwork to ensure a smoother journey before executing an actual documentation task.
Now, to create good documentation, there are five general steps you can follow:
Planning
Planning is a very important step. You need to plan to execute well. By planning, we mean you want to provide yourself a framework to work with in creating the documentation.
The plan doesn’t necessarily have to be complete. It could be incomplete or sketchy. It doesn’t matter as it would get modified severally along the way. What matters is that it gives you a first start on what to do.
To develop the first elements that would compose this initial plan, there are important questions you want to ask yourself:
- What are the expectations and timelines for the documentation: when is the deadline? In three weeks’ time? Four weeks? Don’t be surprised! Most documentation projects tend to have very short timelines because they start so late in the product development process and companies still want it ready on product launch!
- What content resources and source materials are already available: product design documents, product API references, and demos?
- What documentation sections (tutorials, how-to, explanation, reference guides) are needed for documenting the new product?
- What other output formats are required in creating the documentation? PDFs?
- Who are your contacts within the company? Software engineers? QAs? Product managers?
- Where would the documentation be published — on the developer portal? Or on a dedicated subdomain website?
- Would there be any need for pre-releases for early access partners? When is that?
These and other questions, depending on your circumstances, need to be mapped out in advance of the actual writing process.
Information Gathering
Next up, you want to start collecting the information needed to create the documentation.
There is some source content you can be certain would be available, so you just locate them and source them from the right contacts within the company.
The product design document is one such source content. The product design document gets created at the beginning of the product development process during the product idea proposition and validation period.
It is written by the product team and it is the blueprint for the product design. It lays out the need for the product, that is, the problem the product is to solve, and the features expected of the new product on implementation.
The actual code implementation of the product might not reflect the product design document completely as it is expected that things might change along the way. However, the document should still be close to the real product.
So the document still constitutes a goldmine of information that would be useful for the documentation. Since it is written by the product team, you should be able to source it from your contact in the product team.
Another source material is the product demo. This would usually be created by the engineering team. More specifically, the set of engineers who executed the project.
A sample app would usually get created for testing the product. If the product is an API, then the sample app would be one that is just used to make requests on the API, and log data responses to a console or to a terminal.
The simplicity of such a sample app is actually what you seek at the moment. Something too complex would be of little use.
To help you gain a better understanding of the product, it is advisable to play around with the product demo yourself. If you are not very technical, you could have the engineer who created the demo help set up the demo app on your local machine. Then, you can play around with it and get to see how it works.
Then, you should also try to lay your hands on reference documentation, if available for the product. Reference documentation is associated with native or web API products.
Developers would most often populate this documentation themselves, building it automatically from the source code using doc-as-code tools like Sphinx or Javadoc.
This documentation curates a list of the classes and methods of the product for native APIs products; or a list of endpoints and methods for web API products. This could serve as a good source of information on the technical details of the product.
Conducting Interviews
This is also part of the information-gathering process, but it requires a whole different approach compared to collecting together source materials.
This is the step that would call in your communication, time management, empathy, and most of your social skills.
Based on the plan you laid out in creating the documentation, you would soon discover a lot of gaps that need to be filled once you have reviewed all the source material you gathered.
Gathering this information would require interviewing your contacts in order to get more information.
To help you narrow down to the most essential, here are four key contacts you want to interview for the documentation:
- Engineering: the team that wrote the code for the product.
- Product/product management: the team that planned the product laid out the product strategy.
- Partner engineers: the team that helps users implement the product.
- Quality assurance engineers: the team that tests the product.
Each of them has a different perspective and input to contribute to help with the documentation, so it is important you don’t overlook any of them.
The engineers would be very key in helping you understand the technical details of the product. They also help you better understand the sample app and how it works if you ask for further clarifications on that.
The product managers would be best in helping you understand the product messaging, use cases, audience analysis, and concepts related to the product.
The partner engineers or developer relations(DevRel), as they are commonly called today, is the group that interacts with the users to help them implement the company’s products.
They also have useful input to contribute, especially on user feedback which could be useful in creating the documentation. They could provide more information on the use cases, adding more nuanced information your contact from the product management team might not have mentioned.
The QA engineers would be useful, especially in helping you understand the limitations of the product or get to know of bugs in the product. This would be key in ensuring transparency of the documentation.
It is also important you understand that inputs from the different teams might also conflict. For instance, the product management team might be very inclined towards presenting the product in the best positive light possible and might try to persuade you to omit any limitation of the product from the documentation.
In this instance, it is best to consider your position as a technical writer. You are a user advocate, not a product advocate, so maintaining transparency is very important.
The perspective of each team might also conflict with one another as regards other notions in the documentation. These conflicts are better handled by bringing together the teams and having them iron out their differences.
Writing
Now, it is time to write!
By the time you’ve rounded up collecting source materials and conducting interviews, you should have a whole bunch of content files. Perhaps, you have a single doc where you just copied and pasted all of them. That’s fine.
First, you want to sort the content into the right categories or groups. The diataxis framework could be very useful in helping you do this. In fact, you could use it as a template for designing your documentation content layout.
The diataxis framework divides documentation into four categories:
Tutorials
These are learning-oriented documentation content. They are meant to familiarise new users with the product. The content you want to include in this category would include getting started tutorials, installation guides, and hello-world tutorials.
You can learn how to write good tutorials from this article.
How-to guides
These are problem-oriented in nature. These are documentation content that helps users unblock themselves in executing tasks with various features/functionalities of the product.
A how-to guide is a good place to educate users on what your product is capable of. The content you want to include in this category would include advanced guides, and generally, how-to guides.
You can learn how to write compelling How To guide.
Explanation
These are understanding-oriented in nature. This is a good place to help users better understand your product. The content you want to include in this category would include concept guides and product use cases.
You can learn how to write an explanation article and guide.
Reference guides
These are information-oriented in nature. This content focused on the technical details of the product. The content you want to include in this category would include API reference guides or reference guides for native APIs.
Once you’ve sorted out the content into their different buckets, then the next thing is to create an outline for each group. By creating an outline for each group, you want a high-level description and sections for the content in each group.
Don’t worry yet if the outline is not comprehensive enough yet. As time goes on, you can always modify it as you gain more clarity and ideas for new content.
Next, you want to set up review meetings with your reviewers. They would most likely be the contacts you engaged with in gathering information earlier. This is important because they might be busy in their own right, and it is important to inform them early and get on their calendar early on before all the open slots on their calendar are taken up.
Lastly, you can now go ahead and write the first drafts. Here, it is important to put in measures to ensure you keep to the timeline so you don’t fail to meet the deadline.
Do you write best in the morning? Then, don’t wait until noon to begin writing.
Do you prefer to write in sprints? Then you should divide your writing tasks into chunks, spreading them across the entire day, and timing each sprint.
If you are a professional writer, you should have already mastered yourself in this realm, knowing the conditions necessary to ensure you write best and meet your deadlines.
Editing and Review
Editing your content comes before review. During editing, you might still be the only participant in the documentation process, so you still have room to make a lot of changes.
Once you are done editing the content, cleaning up grammar issues, and making sure it is technically correct to the best of your ability and the information available to you, it is time to bring in more participants. This is the review process.
The review process, like the information gathering, will call up your social skills.
You need to understand your reviewers to ensure you are engaging with them correctly to ensure you achieve your goals.
- What is their preferred communication channel? Email? Slack?
- Would they prefer to review the documentation beforehand, then discuss changes during a review meeting; or would they rather read and discuss the changes during the meeting?
- Would it be better to work with reviewers one at a time or all at once?
- Would they prefer to review the documentation in chunks or in large amounts?
- What are their busiest days of the week?
You should consult each reviewer on each of these questions, but you don’t necessarily have to ask them all the questions. For instance, if you know the days of the week that are the busiest days for one of the reviewers, then you know not to schedule a meeting on that day.
Once you have gotten all these questions answered, it is time to commence the review process.
The review process should be made up of review cycles, with changes and edits to incorporate at the end of each review cycle.
Regardless of the review path, you choose to follow—working individually or collectively with reviewers—one of the issues you will have to deal with during the review process would be a conflict of perspectives between the different teams reviewing the documentation, say the product management and the engineering team.
I mentioned this earlier during the information-gathering process. You will have to deal with it, and even more, during the review process.
When caught up in such conflict, it is best not to try to introduce your own view or take sides. Instead, bring both sides together and try to find a compromise that appeases both sides.
Publishing
It is time to publish your work!
As you plan to publish the content either on its own subdomain or by integrating it into an existing developer portal, you want to take note of a few points.
If you are publishing on a separate subdomain, then you want to scan through the documentation to ensure they are properly linked and cross-referenced.
If you are integrating the documentation into an existing developer portal, then you want to ensure it is properly integrated into the existing content and does not stick out.
Then, you also want to add metadata as links to release notes.
If there is any need to optimize some pieces of content in the documentation to ensure they are discoverable on SERP, then, you can also do that here after consulting the right authorities.
However, it is best to also have considered SEO during the writing stage to ensure you have already incorporated SEO keywords.
After performing all these optimization tasks, then you can make the documentation live and publicize it too.
Thereafter, you can celebrate the new release, and start preparing for the next documentation task or rounds of feedback from users of the documentation.
So that’s it for this article. If you found it useful, give it a like and drop some comments.
Contentre helps technical writers stay organized and gain more clients. Grow your technical writing career in one place.
Now that you’re here, let me briefly recap the most important features Contentre can offer you:
- Organize your content in categories, topics, and tags
- Create and manage multiple clients
- Create and manage multiple personalized portfolios
- Get statistical analytics of your content revenue, top categories, and tags.
