SoD and technical documentation in an open source organization

Documentation in open source organizations is a complicated job because there are so many new edits and issues occurring daily, that without a dedicated team, they become challenging to manage. Since open source organizations mostly rely on volunteers it is not unusual for a small task to take longer than if full-time team members were dedicated to it. Time is of the essence when improving documentation; since as contributors continue to add value to the organization, chances are there will be more work content to continuously work through. Season of Docs (SoD) aims to aid with documentation in an effective way.

SoD creates an environment where freelance technical writers can work with an open source organization for 3–5 months. The technical writers can get paid and the organizations get a dedicated individual to take care of their documentation —a win-win for everyone.

I had the opportunity to work with ESLint under SoD 2020, where I was able to learn quite a lot, with the aim to improve and organize the Configuration Documentation of ESLint. From understanding the work of ESLint and the structure of the existing documentation to managing a short-term project and collaborating with other volunteers, the project was filled with learning experiences. The best aspect was that I realized the worth of my contribution, but also felt appreciated all along. Often, technical documentation and communication are not given much attention but with SoD it was different.

The Positives

A different perspective

A freelance technical writer, in most cases, is a person who is not a part of the organization. An external perspective with the existing documentation can point out some issues which may otherwise go unnoticed. Additionally, since the freelance writer is entirely dedicated to the task they’re able to solely focus on that task.

Collaborative environment

One of the best things about open source organizations is the level of collaboration. While working in such an environment, where everyone is so willing to help and to give valuable input, a freelance contributor does not feel alienated at all. There is a lot of valuable feedback and the work of a technical writer is both respected and appreciated.

Some Challenges

As in any other project, documentation in an open source organization is not free of some hiccups.

Understanding the content

Freelance technical writers have limited time to get acquainted with the objectives and the content of the open source organization, making things a little hard if the writers have not previously interacted with (or heard of) the organizations they are working with. Reflecting on my own experience, I feel that this was a major concern for me since I had no previous experience with linting software.

Thanks to the 'community bonding period' however, which lasts for almost a month before the project officially begins, the freelance writers can get some understanding of the organization and the content.

Time

Since most of the contributors are working voluntarily, their engagements can prolong the process of review and feedback, which can make meeting the project deadline feel challenging at times

Overcoming the Challenges

It doesn't matter if you're working under the SoD umbrella, contributing to strengthen your portfolio, or trying to gain more practical experience, the following tips can be helpful.

• Communication is key. It is important to convey your concerns regarding time, commitments, and other engagements so that the expectations are met.
• Ask questions! You won’t know everything about the project.
• Be flexible. Your project might change after you start working on it, and things don't always go as you planned.
• Use the 'community bonding period' to interact with your mentor and other collaborators, indulge in small tasks, and get to know the people and the organization.
• Value the work and feedback of others. Everyone who is a part of the community is trying to add some value to the organization.

SoD serves as an excellent platform in bringing technical writers and open source organizations closer.

Guest Post by Khawar Latif Khan – Season of Docs Participant