Writing on GitHub II

In a previous post, I spoke about moving to GitHub as a technical writing platform. In this post, I will address some of the challenges I faced, methods of resolution, and future goals as I continue down this journey. If you want to know the exact reasons I have made this change you can review that previous post.

But just to recap some of the largest points:

• Knowledge workers should be consistently producing useful content
• The most precise way of measuring and collaborating on that content is with a version control system
• GitHub naturally presents itself as an ideal platform for this

Writing Modes

When I first started down this path, I wasn’t accustomed to writing in markdown. I typically did all my writing in Google Docs. After migrating some of my existing writing projects to a GitHub repository with this addon, I cloned them to my local machine and started looking for a good markdown editor. This is where things got strange. It seems that writing in markdown has become something of a rising trend to the degree that there are several paid editors on the market with some even requiring a paid subscription. That kind of blew my mind. A subscription text editor? Thankfully, I didn’t capitulate and decided to just use Visual Studio Code as my editor. I had to brush up on the IDE interface, staging and committing changes, and package installation. I few things I liked about this setup were:

• No third-party access to my repository
• Unambiguous git interactions
• Side-by-side rendering of markdown content
• A Grammarly extension (removed from the market place but still available here)
• Options to use “second/external brain” approaches with things like Foam

The exercise proved beneficial but one aspect of the workflow I still really didn’t like was the Grammarly integration. By accident, I discovered that editing files directly from within the browser on the GitHub website itself proved sufficient for most things I wanted to do. Talk about going full circle. After adding GitHub Writer, a browser extension that made editing markdown files even more friendly and realizing that the Grammarly browser extension worked as well when this extension was enabled, I started to really fall into a groove. What’s cool is that all my content is still available locally if needed (meaning I can interact with it with any application on my machine) but still conveniently available to be edited within a browser window. It’s really the best of both worlds.

Image Management

Image paths in GitHub repositories can be tricky. While GitHub does offer an image hosting CDN mechanism, there is no mechanism to view-all-uploaded or delete images once uploaded. I didn’t want to use dropbox as that entire domain can be blocked on some corporate networks so landed on a slick Imgur workflow that handles my local screenshot needs as well. With this mac app and an Imgur account, you can drag and drop images to be uploaded or just take any screenshot and it will be uploaded to your account and the link copied to your clipboard.

Organization and Workflow

I am staying organized on priorities and in-flight work with a GitHub project board. I recommend creating your main project board at the topmost level of your GitHub account so you can use a single cross-cutting board to link issues to any of your repositories. If you make it at the level of a single repository then it is scoped to that repository. Milestones can be used to create a cadence if you are working in sprints.

My workflow starts with creating an issue. I’ll add miscellaneous thoughts into the issue as ideas come to me on a topic and also talk through issues with peers. When it seems the ideas are fleshed out sufficiently, then a new markdown file can be created in the relevant repo and a first draft created and committed from those developed notes in the issue. This is the issue that started this very post.

Presenting Content

I’m most frequently working in private repositories but have a need to present content to people who don’t have access. This is where HackMD comes in. It allows me to pull in content from any repo (even private) and present it as a slideshow. Any updates to that file in git can be pulled into the HackMD version and it also allows pushing the other direction as well.

Future Steps

One of the several motivations I had in making the move to writing on GitHub was to encourage a don’t-break-the-chain pattern. This is useful as can be seen from my commit history since June. I even went to the trouble of adding my commit-graph to my Apple watch with this app. I consider this a good first pass at what I’m trying to accomplish but I think I’m increasingly eager to move into the next step of quantifying this output.

The next logical step will be to quantify daily word count, and not just commits. The GitHub commit-graph counts two commits of one word each as more than a single commit of a thousand words so it’s really not a good proxy of consistent content creation. Just like lines of code, word count is not a determining factor of good work but it means some activity/effort is happening. I’m hopeful that I’ll be able to accomplish something like this with a GitHub action. Secondly, I’d really like to be “releasing” more frequently. If authoring can be construed as development and publishing (as a presentation, article, or documentation) can be viewed as deployment, then I need to deploy a lot more frequently.

This is the conclusion of my second update on this journey. Feel free to follow me on Medium or GitHub to get updates or possibly collaborate on future endeavors.