Get Better At Technical Writing 3: Documentation as a Service

Introduction

Open Source contributions are not restricted to just code, as is believed by most developers. Documentation is a recognized and valid means of contributing to open source projects. In this article, documentation is treated as a service (DaaS), similar to Infrastructure (IaaS), Platforms (PaaS), etc.

Technical writing is an important part of software development because it serves as a bridge between the developers and the users. The ability to write good documentations is a must-have skill for every engineer and researcher; you should probably take a course on it if you often find yourself doing stuff other people need to know about.

Writing documentation for a software is not just something you do to fulfil all righteousness. As stated in a previous issue in this series, it can be the defining difference between useful and useless software. Best case scenario of a poorly documented software: hundreds of emails get shipped to support team. Worst case: it doesn't get used.

Let's look at possible ways you can write or improve DaaS.

DaaS in Your Learning Journey

In the tech ecosystem, everyone is plunged into an infinite loop of learning. Over the years, cognitive psychologists have proven to us that an effective technique to solidify knowledge of something learnt is to teach it. You can teach your pet, yes, but nothing stops you from teaching people who would find it useful.

Looking for topics to write about while building your tech career? Write about your learning journey.

It could be in the form of daily or weekly entries for a personal learning challenge, or creation of content based on what you've learnt and sharing with people. It can also be writing end of year reviews and new year resolutions, as is common in the Nigerian Tech community.

Chances are that you personally will sometimes have to refer to your own articles later in the future — a very common thing to me and some of my friends.

Furthermore, some recruiters would love to see these blog posts to confirm how long you have learnt a language or if you learnt it thoroughly. In these cases, some bootcamps like HNG Internship program has made it compulsory for enthusiasts to blog about their learning experience.

It can also be service to yourself in the form of a self-accountability system to continue learning. A simple example is having to tweet everyday about your #100DaysofCode challenge.
Experience gained through this means can help you land a passive income stream as a contract Technical Writer.

DaaS in Open Source Contributions

Technical writing is an open source experience in a sense. Providing documentation for software is a fine way to contribute to open source.
For example, during Hacktoberfest, you can contribute to documentation in the following ways:

• Review and updating existing documentation
• Test company official SDK in some use-cases and add them to examples.md file in the repository (code required)
• Write documentation and provide examples for software built by coders during open source contributions.

DaaS in Product/Software Support

Writing example use-cases for a software — as mentioned earlier — is one means of providing support to potential users of that software.

DaaS in an Agile Team

Working in a company as a technical writer, you will have to work hand in hand with the software team. In that case, your team may follow the Agile methodology, making use of a standard project tracking system like Jira.

In this situation, you should make use of such project management software to keep track of your tasks, review your documentation, raise issues to developers and staff, assign tasks when possible, etc.

If the dev team makes use of X, look for a way to make use of X also. In a future issue, I will expound on how to do this.
Asides working in sync with the dev team, you also have side jobs like:

• Reviewing published contents, updating and republishing them
• Discussing with the team and staff where needed
• Studying the software you're documenting through and through
• Checking customer support for complaints that your writing can fix
• Others

DaaS Tools

In documenting, several tools are available to make the job easy for you. They are helpful for specific functions, like API documentation or Markdown writing. Some of these include:

• Postman
• Swagger UI
• Apiary
• Readme.io
• Docusaurus
• Gitbook
• Read the Docs

To better improve your writing, you may use softwares like Grammarly keyboard, a Thesaurus app, Notion etc.

Conclusion

In this article, you learnt about different means you can write DaaS.
When next you start writing, put in mind that you're writing for your future self, for others to learn that skill thoroughly, for recruiters to know you're adept in that technology, for users to enjoy the product, and for your importance to be acknowledged in the team.

Disclaimer!
A couple people reached out to me asking me to collaborate with them and make these write-ups a paid service. I'm open to collaboration or anything, but just not for this.