Github Pages for the Budding Technical Writer (a Review)
Also, an insight into making open-source documentation, poems, books, or other writing projects…
Over the fast few decades, technical writing has become associated with certain kinds of software known as authoring tools. MadCap Flare, Adobe RoboHelp and Frame Maker, DITA/XML based programs, and visual design tools like InDesign are some of the most popular.
However, I quickly learned that these familiar, established tools may not play as big a role in my future career as a technical writer as I thought, and this was because of a choice I was making.
That choice was to become a technical writer who specializes in developer documentation, a.k.a. an “API Specialist,” “Documentarian” or “Programmer Writer” or “Documentation Developer.” (The role is called many different things in the software industry, but all agree that the role is a technical writing one.)
In short, that means, when I write documents, guides, instructions, etc., I will need to write them in such a way that the software developers will be able to review them and contribute to them easily.
It just makes sense. Developers do not want to bother learning XML, FrameMaker, or MadCapFlare, and licensing restrictions are another barrier.
This is why developer docs are often written right in with the code itself. Your content doesn’t live in a CMS designed for technical writers or on your computer; it lives where the code lives. (Often, it exists written in markdown.)
And, in many cases, that means it lives on Github (the files are hosted there), and it is run by the version control system known as Git.
Git and Github
If you have never heard of Git and GitHub, no worries! The following software review will give a small glimpse into that world.
You can think of GitHub as an ecosystem that organizations, corporations, and developers collaborate within. When people talk about “open source” software, these tools are some of the underlying technologies that make it all go smoothly.
Note: As someone who only recently learned about them, I can pretty confidently say, that Git and Github are not things to be “learned.” You have to try them out for yourself in order for the concepts to really click.
However, I can reccomend, Github’s tutorials as a good way to get hands on experience: https://lab.github.com/.
“How long does it take to get it?,” you ask… It took me a few weeks.
A Use Case. My Use Case (Whose Use Case? Mine…)
A few years ago, I wrote a free E-Book about my predictions for the future of crowdsourcing, and I hosted the content right here on this blogging platform, Medium.com, so that people could easily access it.
But, making that choice narrowed my options for the future of the book. For example…
- It would now exist as files out of my direct control; I would always have to use Medium.com’s CMS to interact with my content.
- It would not be easy to later turn into an EPUB file or PDF so that people could read it on a Kindle, for example. (I would always have to download it page-by-page as HTML, clean it up, and transfer it to another program if I wanted to do that.)
- It would be difficult to let just anyone come in an make changes to it. I would have to know who the person was, and go into Medium.com to give them permissions to edit.
Luckily, now that I have learned how to use GitHub, I may have found a solution that allows me to:
- Let anyone else on GitHub make suggested edits (called “commits/pull requests”). Then, I can then accept or reject the changes…or just start a conversation with that person under the “Issues” tab.
- Upload the HTML files that Medium.com let me download. (I will have to figure out how to make them into Markdown files later, files which can be more easily turned into PDF’s or EPUB files.)
Enough talk. Let’s test this idea!
I started with building a repository (i.e., a collection of files associated with your project on Github).
I named it. Then, I created a new repository (Called a ‘repo’ for short, in Git/GitHub speak.)
Now, click “Upload Files”.
Submit changes and describe the changes (i.e., “commit” in Git/GitHub speak.)
Now, go to settings, at the top of the page, and, from the settings page, scroll down to the section for “GitHub Pages”.
Choose “Master Branch”, click “Save,” and it will show you the link at which your content can be seen.
For example, you can see one of my chapters, that lives on GitHub as a markdown file, at this link:
https://crowdsourcingkc.github.io/crowdsourcingshortcut/ch-2
You can compare it with the one hosted on Medium:
https://medium.com/@CrowdsourcingKC/ch-2-social-search-74f05dfd5d25
Success!
Note: My next steps include changing it from HTML to the GitHub flavor of markdown, and then finding a Jekyll theme that will make it look good. (This will give my readers a better reading experience and attract more contributors.)
Conclusion:
Although there is a steep learning curve to GitHub. Using GitHub Pages to publish your content is pretty straightforward.
Using it is little more than enabling some settings, making a few choices about how the content will be presented, and then making sure that everything is properly linked together.
With my limited experience, I recommend it wholeheartedly.
However, if you are feeling ambitious, there is another service that does something similar. The service is called Netlify, and they similarly let you “deploy” your GitHub repository as a website. But, they offer a lot more bells and whistles. I tried Netlify the other day at a hackathon (the first hackathon I’ve ever done, btw!), and I can recommend it too for ease of use.
Note: If you are looking for a criticism of GitHub pages, I found this one, but, admittedly, it was a bit over-my-head:
Want a more guided introduction to these concepts?
If you would like to get started learning how you can put written content on GitHub and invite collaborators, I recommend this video tutorial series:
It’s called GitHub for Poets, and It gave me a great/fun first look into this fascinatingly brave new world of online collaboration.
