Upgrade to Pro — share decks privately, control downloads, hide ads and more …

The technical writers guide to contributing to open source projects

The technical writers guide to contributing to open source projects

The documentation of an open source project provides an avenue for users to understand the project and contribute to it. Surveys have even shown that good documentation saves as a sign of an open source project's healthiness.

Yet, few open-source projects can claim they are well documented, and many others struggle to keep their documentation up to date.

As important as open source projects' documentation may seem, most technical writers shy away from contributing to open source projects because they don't know how to or they are influenced by the stereotype that only software engineers can contribute to open source.

This article aims to provide an introductory guide for technical writers who want to contribute to open source projects. It will cover how to get started, best practices, benefits, and insightful resources for further learning.

62efdbbae2cf211e48bd16f1948ea1f4?s=128

Edidiong Asikpo

October 20, 2020
Tweet

Transcript

  1. The Technical Writers Guide to Contributing to Open Source Projects

  2. Hello! I am Edidiong Asikpo. A developer advocate and technical

    writer. 2
  3. What is an open source project? An open source project

    is a project whose source code and documentation are made available for use, modification, or enhancement by anyone in the world. 3
  4. The state of open source documentation 4

  5. 5,500 Randomly sampled respondents 5

  6. 93% Complained about incomplete or confusing documentation in open source

    projects. 6
  7. The documentation of an open source project is arguably as

    necessary as the software. 
 
 Therefore, technical writers are as important as software developers in the open source ecosystem because humans can’t use or contribute to what they don’t understand. 
 7
  8. Why technical writers are important in open source. 8 Based

    on the survey analysis, you will agree with me that there are different people who decide not to use an open source project or contribute to it because of the documentation. When technical writers come onboard and become active open source contributors, this problem will be solved, and more people will contribute to or use more open source projects. 

  9. How to contribute to an open source projects as a

    technical writer Find a project The documentation of so many open source projects is either incomplete or confusing, so there are many projects that you can improve. Identiy an issue If you don't see any open documentation issue on the repository, then use the project and identify things that should be documented but haven’t been. Send a pull request Identify and understand the open source project’s review process. Then follow that guide when submitting your pull request. 9
  10. Some notable best practices Follow a style guide (if it

    exists). The page title should reflect the content of the page. Always define what the page is about in the first paragraph. Consider your audience when creating content. Avoid duplicating content. 10
  11. Benefits of contributing to open source projects as a technical

    writer Your writing skill will improve. You expand your network. You can get recommendations and referrals. You can get accepted into the Season of Docs program. You become an Open Source contributor. 11
  12. Conclusion 12

  13. 13 Thanks! Any questions? Blog
 edidiongasikpo.com Twitter
 @didicodes