At the heart of open source is the community that drives it. The people are the engine that powers all the great benefits that open source provides. It is some kind of symbiotic relationship where software is made available to the public and the public in turn can support, secure, and improve said software.

Much like every human-centric endeavor, a lot rises and falls on communication. It is therefore follows that to drive further usage and innovation around a product, communication in the form of technical writing is imperative.

This article aims to provide a guide for technical writers who want to contribute to open-source projects. It will cover key components of technical writing and its impact in building vibrant and thriving communities.

Forms of technical writing

• Documentation

• User guides and tutorials

• Articles

• Blogs

• White Papers

The role of technical writing in open source

Generally, technical writing can help improve the quality of software.

• It keeps people abreast with the changes made on the software.

• It informs people of all aspects of the software being improved upon by the maintainers.

• It educates people on every aspect of the project.

• Technical writing when done right can drive the usage and adoption rate of open source projects.

Elements of good technical writing

Simplify complex information

Take complex ideas and break them down to a point anyone can understand and interact with. One major challenge of using software is how abstract and complex it can get. Such a good technical should be able to cater to the very skilled and the not-so-skilled. People are more eager to use a product if they can understand it. What can be obvious to someone who is a senior can easily be confusing for a junior. So, it's good to break things down into simpler bits for better understanding.

Give room for feedback

Feedback is highly essential as it serves as an opportunity to improve your writing and possibly broaden your perspective on the subject matter. This can be in the form of comments or questions. People are more eager to contribute if they feel heard and their opinions are valued.

Be clear and concise in your presentation of information

It is important to present information in a way that isn't ambiguous and gets the point across. Go straight to the point and incrementally arrange your thoughts to make comprehension easier.

Utilise mental models and visual aids

Use visual devices to represent information e.g. illustrations, tables, graphs etc.

Follow the coding standards and file guides(if any)

It's important to be orderly in your presentation of information hence the need to follow the standards and guides if any. If you’re upgrading documentation for an existing product, read the existing documentation. This will help you to know what is expected of you.

Conclusion

One of the goals of technical writing is to make the user of open-source products much more familiar and comfortable with the product. If that is achieved, you'll have more people using your product and enjoy the benefits of a strong, robust community.