Contents
Introduction
After weeks of trepidation, I finally took the plunge (ok—a timid wade) into open source contribution and made my first pull request on Github! I’ve only taken a small first step in contributing, but I thought I would list out the resources that have helped me get to this stage from knowing absolutely nothing about open source—in case there are those of you out there thinking about open source contribution and have no idea where to begin. I’m basically summarizing all the Googling I did and pointing you to sites that have been useful to me.
What does it all mean?
Open source is any program that makes its source code freely available to anyone who wants to use or modify it. It’s the complete opposite of a proprietary software like say, Microsoft, where you’re required to comply with a license agreement that doesn’t let you share or modify the software code.
Git is an open-source version control system and a command line tool. Version control is a type of software that tracks changes to a file(s)—or takes a ‘snapshot’ of the files in your project—and lets you revert to any specific version or snapshot later.
Github is a platform with a graphical user interface (GUI) for managing Git projects. Github hosts the Git system. It’s a community of millions of developers building and sharing software, and a place where these developers store their projects. Anyone can download the files related to a project and use them or contribute to them.
API (Application Programming Interface): On a very simplistic level, an API is something that lets applications communicate with one another. Let’s say I’m creating a website for my new restaurant and I want to embed a Google map to show the restaurant’s location. I can use an API from Google for this very purpose—this will let my website communicate with the Google Maps app. To use the API, I would have to consult the API documentation as a reference to write the code my website would need to interact with Google Maps.
APIs need to be documented so that developers (or anyone) who want to use them know how to use them, i.e. how to communicate with the API. API documentation is usually written for developers who would prefer lots of code samples in the documentation rather than say, screenshots.
Learning how to document APIs
Quite simply, your one stop shop for learning about API as a complete beginner is this excellent documentation course on Tom Johnson’s site. I invested a bit of time on his very comprehensive (free) API course and I highly recommend it.
Not only does the course cover a huge amount (putting you in the shoes of both a developer and writer), but Tom also peppers it with heaps of practical exercises that make you feel smarter than you did an hour ago. It certainly gave me the confidence I sorely lacked to venture into Github. In case you’re interviewing for an API doc writing position, the course provides you with the appropriate vocabulary and background knowledge you need to ace that interview!
I initially did an Udemy course by Peter Gruenbaum, but in hindsight this would have been a useful add-on after Tom’s course. I was still lacking the conceptual knowledge about API’s to fully appreciate Peter’s course.
Getting started on Github
I recommend this 5-step plan:
- Get familiar with Git commands and lingo (repo, PR, branching, forking etc.) I found this tutorial quite useful especially with getting me comfortable using the command line.
- Sign up for a Github account and play around in it, creating your own repo and writing something in Markdown.
- Learn the standard workflow for contributing in Github (forking, editing, submitting a pull request (PR)).
- Refer to this page on Tom Johnson’s site on how to get started finding your first open source project.
- You may find it helpful (I did!) to watch a technical writer go through the entire process of finding a project, editing and submitting a contribution on Github.
Conclusion
Most of the sites I’ve linked to will overlap sometimes in terms of the information they provide—this is a good thing. Most discomfort or fear is just a lack of exposure to whatever is making us uncomfortable (deep!), so the more information gets repeated, the more it will make sense.
If you’re feeling overwhelmed at the thought of contributing to open source documentation, know that this is perfectly normal. I found it quite comforting that my intimidation was understood and shared by the tech writing community online.
0 Comments