I presented this talk at the Write the Docs Meetup Melbourne in February 2020.
It is a retrospective on the Google Season of Docs 2019 program, and covers some of the hurdles I experienced coming in to open source from the corporate world.
For Season of Docs 2019, I worked on a project for the Open Source Geospatial Foundation (OSGeo). My project report describes the work I completed in detail.
Open source culture shock
Tech writing is tech writing. In an open source environment, it’s the surrounding pieces that are different.
You need to understand your PAD (purpose, audience, delivery) and that means adopting the culture of the community and learning their tools and processes.
Eric S Raymond wrote a book called “The Cathedral and the Bazaar”. In it, he describes open source development as “a great babbling bazaar of differing agendas and approaches … out of which a coherent and stable system could seemingly emerge only by a succession of miracles.”
Heighten your awareness of the group
Most open source communities are distributed communities. According to Fabian Pfortmüller, that means they’ve probably developed over a long period of time, have a strong sense of shared identity and they want to co-create or feel co-ownership. Key to understanding communities: the centralized to distributed spectrum
Remember that engaging the community takes time and effort. It can be as time-consuming as doing technical writing work.
Abide by the Code of Conduct.
(Shout out to @peitschie for helping me with culture shock.)
Show up. Do the work.
Guy Martin says that you have to earn your role in the community. “The only way to do that is to gain credibility and make contributions.” Building leadership in an open source community
In open source, you live and die by the work that you do. Trust and reputation count for a lot. Commit to doing the work, and do the work that you commit to.
Follow the Contributor’s Guide (if there is one). Otherwise show respect, and be inclusive and honest.
Overcome technical hurdles and work out process kinks. Look for a “good first issue”. Jonathon Beckman writes “…don’t try to show off your skills just yet, in fact look for the easiest thing you can find. This is a great way you can get used to how the communication will work between you and the project maintainers.” Open-Source: What it is and why you should be involved.
It can’t hurt to brush up on other open source tools which you may need to do your work, like Git, Markdown, Linux and working with the command line.
Why you should do Season of Docs
You get:
- Communities who have opted in
- A defined piece of work with a deadline
- A mentor
You also get personal growth! Participating in Season of Docs gives you the opportunity to build your reputation, learn new tools and gain writing experience. Which all adds to your employability, connections and future job opportunities.
Personally, I learnt a new markup language, stretched my git muscles and made new friends.
Image credits
All images from Unsplash except where noted.
- The future is now, Alex Knight
- Dip your toes in the water, Jorge Gil
- Snuggle, freestocks.org
- Framework, Bernard Hermant
- Good vibes, Allie Smith
- Babbling bazaar, Bit Boy (flickr.com)
- Direct message, Volodymyr Hryshchenko
- Telephone, VanveenJF
- Envelopes, Joanna Kosinska
- Block tower, La-Rel Easter
- Learning curve, Tom Mussak
- Maze, Benjamin Elliot
- Hello world, Kobu Agency
- Welcome sign, Aaron Burden
- Container, Kelly Sikkema
- Mentor buddy, Alvan Nee
- Seedlings, Francesco Gallarotti
- When in Rome, Nils
- Do the work, Plush Design Studio
Further Reading
Take a look at the Season of Docs Results page to review the projects that were completed and read about other writers’ experiences.
Read Sarah Maddox’s comprehensive write-up of the results on her blog ffeathers.
Check out the #open-source and #community-help-wanted channels on Write the Docs Slack for opportunities to get involved.
Follow the Google Open Source blog for updates.
