Figure 1: Open source projects are resourceful for developing new skills and building new industry connections
This blog post summarizes my technical communication learnings while working as an open source contributor with CircuitVerse.
Documentation audit is key: To prepare my technical writer application, I audited available documentation of five organizations for the following factors:
- What documentation is available?
- Who is the target audience?
- Does it cover all the functionality?
- Does it cover end-user needs?
- Is the documentation any good?
*A special shout out to Audrey Tavares (a past-participator of SoD 2019, Oppia) for answering my queries and guiding me through the process.
Know your audience: When SoD concluded in December 2020, I had produced a series of video tutorials and rewritten the complete documentation for the CV simulator. You can find the complete project report here.
Audience analysis is key to the success of a documentation project. Do your research and ask enough questions to understand your audience and discover vital facts.
In my case, I concluded from my initial findings that the primary audience were students, but the mentors corrected me that the primary audience are educators. This provided a cue for the team that the message is not clear and we revised the content layout to cater to the primary audience.
Secondly, avoid assumptions, and be prepared with agreeing to disagree––conflicts can be healthy!
Write documentation for an evolving platform: Documentation empowers users to feel confident about the product and build trust. One of the key pain points of working on open source documentation is that the platform is continuously upgraded with new features and functionalities. So how do you strike a balance?
While the CV videos had some UI discrepancies, I focused on making sure that the user guide content (that is live) is detailed enough, and gives users clear instructions on how to accomplish a task. I learned that videos play a key role in demonstrating a workflow while the text documentation must be detailed and updated frequently.
Build up developer and documentation tools proficiency: Contributing to open source projects expands one’s familiarity with real world practices, including working with different tools like Adobe Camtasia, GitHub and Markdown. While my comfort level with GitHub grew, I learned better practices for working with Markdown for a large data set. I used the Docs to Markdown add-on for Google Docs to transpose the content in markdown before uploading it to GitHub.
Focus on fluid communication skills while working with subject matter experts: The SoD opportunity allowed me to experience working in a distributed, collaborative environment across borders and geographies––replicates the traditional corporate world.
While my mentors were receptive to my suggestions, I made an effort to keep them apprised about the progress and missing deadlines of the project. For instance, I improvised the documentation deliverable midway with their consent. I realized that it was important to have good, clear documentation available for the available popular topics before adding new content.
When my mentors and I were in doubt, we reached out to the CV Slack community for user feedback on different aspects.
Warming up as an Open Source Contributor
Although my project with CircuitVerse has been successfully completed, I look forward to my continued journey with CircuitVerse, and continued open source contributions with other organizations in 2021. If this is your first time applying for Season of Docs, refer the FAQ for technical writers to gather more insights into the program. You can also give a shout out to the extremely helpful program admins at season-of-docs-support@googlegroups.com or post your queries on the Season of Docs Slack channel.
Guest Post by Pragati Chaplot Jain – Season of Docs Participant
