30 Oct 2018

Hacktoberfest - Week Four

Hacktoberfest week four! In keeping with the theme I set last week I continued to improve open source project documentation as part of Hacktoberfest. This week I returned to dplesca/purehugo, the theme I use for this blog, to help out with improving some areas of the documentation I noticed could use a bit of polish during my first contribution to the project during Hacktoberfest week two.

In dplesca/purehugo#28 I rephrased the section of the README.md that deals with code syntax highlighting on generated blogs. As I mention in the issue, it seems as though the original author simply missed a word when writing the section:

All you need to do is to let rainbow.js the language of the highlighted code […]

which should instead read:

All you need to do is to let rainbow.js know the language of the highlighted code […]

The simple fix in this case would be to add the missing word. However, since I knew I would be editing this part of the document anyways, I decided to take a bit more time and rephrase the existing wording to simplify the instructions and use more specific language to instruct new users what they need to do to get the highlighting library to pick up the desired language. I also added a full example of how to apply Go syntax to a code block using Markdown, as I find seeing complete code samples or full examples in documentation to be very helpful when I’m learning a new tool or framework, and serve as quick reminders if I’m returning to a tool or framework I haven’t used recently to get me back on track.

This week turned into a twofer because while I was working on dplesca/purehugo#28 I noticed a small spelling error elsewhere in the README.md file and submitted dplesca/purehugo#27 to correct a word in one of the document headings. I only noticed the spelling mistake as I had just set up proper spell checking in Visual Studio Code using Spell Right by Bartosz Antosik to warn me about typos and other spelling errors. I had been under the impression that VS Code shipped with spell checking by default but this does not seem to be the case. Further, the VS Code spellchecking addon I found published by Microsoft is marked as deprecated and suggests finding an alternate addon. Correcting minor typos in documentation is small potatoes compared to some other Hacktoberfest contributions, but they are important changes that affect readability, comprehension, and the flow of the document(s) in which they occur.

The end of Hacktoberfest is almost upon us, and I have one last post to share about my final contribution this month. Look forward to a piece about my first major contribution to a Rust project!