Technical Documentation and Open Source

People love open source software. Firstly, the code is open, so it feels more secure to work with a product once you’ve seen its insides. Secondly, you can measure your own worth by trying to contribute. And, thirdly, open source provides fertile soil for online communities, and being a part of them can be a fun and enriching experience.

But all this stuff is about code, what about other things you can open source? Specifically, what about technical documentation? As you understand, most open source projects require input from technical writers. And, unfortunately, quite often, open source user manuals are poorly written or absent altogether. This hinders development processes and scares away potential contributors.

If you really want to help a project out as a technical writer, gain experience and work with peers, or, maybe you are looking for a painless entry point into open source coding, you can try getting into the field of open source technical writing. And, we are going to guide you through the essential steps you should take to do so.

Basic Guidelines for an Open Source Tech Writer

Choose a Project to Contribute

Don’t overestimate yourself, be humble with your first projects or you’ll end up being in over your head. Choose something you feel like you can really do perfectly, else you will end up with a mixture of disappointment and lowered self-esteem. Besides, remember, that open source is often forum or community-based, so if you mess things up, prepare to be criticized. We don’t want to frighten you, but, seriously, it is always better to slowly work your way up to the top.

Research the Project

There are two types of research to keep in mind actually: subject research and looking for things to contribute/improve in the open source documents. These two are closely connected. Either way, you are going to start by looking into what is already available.

To figure out what to do, you can start off by checking help topics for gaps, but that can be time-consuming. Another approach is to look for short topics that feel more like placeholders than real content – these sure need to be re-worked. You can come across them while initially researching the subject matter. Don’t forget to mark such topics somehow as you might want to return to work on them in the future.

As a rule, in open source documentation projects, there’s a backlog of things to be done. This is by far the easiest way to figure out what can be contributed. Going through documentation is a crucial step – you get the chance to understand the current structure and style. When people with different backgrounds and different approaches to help authoring start writing content, consistency is hard to maintain. With that said, let’s move on to the next step.

Study the Guidelines

Hopefully, there is a complete style guide for technical writers attached to the project. If there’s none, look for any sort of guidelines and instructions.

You are going to pick up on some things while going through what’s already written anyway. So, pay attention to things like a font family, font size, font color, headings style, screenshots format and resolution, how terms and abbreviations are handled, how warning and info boxes look, an average help topic’s size. Pick several topics that represent the overall user manual style and use them as a reference.

Talk to People

Communication with fellow technical writers is part of the open source. And, this is an awesome way to find your niche and choose the right course of action. You can literally go to the forum and ask what kinds of important help topics are missing from the project and what kind of contribution in general is required. For example, you might receive a suggestion to add screenshots to existing topics or add more gifs or even videos, re-work existing help topics, split long topics, work on the TOC, etc.

Don’t be afraid to ask any project-related questions there. People who frequent such forums are interested in the project being successful, so they will always help you out. Another thing you can do is ask for feedback and improve the content you’ve already delivered based on that.

Conclusion

Open source technical writing is a great way to challenge yourself and gain more work experience. The work mechanics are a bit different from common help authoring and you also take more responsibility for what you are delivering because you decide what you do. Through creating open source user manuals, you can truly estimate tech writing skills and see what you are capable of at this stage of your career in technical communication.

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices