After spending my free time of the past week enhancing discoverfoss.com , I decided to reflect on why this blog exists, and why I’m using Hugo to manage it.
Discoverfoss.com came from a desire to give back to the free and open source community which has given so much to me and my family. I’m not a coder. I have no ambitions of being a “Youtuber”. I enjoy writing, and my profession requires long form writing for teaching and manuscripts for public speaking. Free and open source projects encourage volunteers to write documentation which feels like a natural fit with my skill set. So why did I start a blog if I want to write and edit FOSS documentation? Although I write in my vocation, I don’t write manuals for programs or lesson plans focused on technology. I also don’t use in my vocation or daily life the tools used by FOSS projects to produce their documentation. Two documentation experiences will help to illustrate this point.
My first exposure in helping with documentation came from getting involved with Fedora Docs. In order to contribute to their documentation, you need a Fedora account that is verified through their Fedora Account System or FAS. This gives you access to Fedora’s Git repositories that are housed on their instance of Pagure. In your Pagure account you have the ability to fork the Fedora Documentation, edit your fork, and make a pull request to have your edits merged into the main documentation. The Fedora Docs community has focused their documentation tooling around ASCIIDOC formatted text files.
Recently, I have helped out the MX Linux team with edits of the manual for MX-Fluxbox. Their process also used Git with GitHub housing their repositories for version control. They use LibreOffice to create, edit, and publish their documentation into PDF manuals. To make my edits, I forked their GitHub repository, edited the LibreOffice file, and made a pull request to have my edits merged. I added an additional file to my branch of the GitHub repository. I created a plain text file that detailed all of the edits I had made to the LibreOffice file. Because the LibreOffice file is a file type that is not supported by GitHub’s builtin editors or viewers, you can’t use the features of the GitHub interface to easily compare them to the original files.
Through these experiences, I identified three areas of growth that would enhance future contributions to FOSS projects.
- I want to increase the quality of my technical writing.
- I want to become comfortable with Git’s work flow and commands.
- I want to become proficient in using all of the syntax in Markdown.
Practicing the craft of technical writing provides the opportunity to become better at it. Blogging provides this practice, but where do I post articles so others can read them and give constructive feedback? Platforms exist that make it easy to get your content in front of an audience. Medium , DEV.to , and Front Page Linux provide platforms for blog content. These platforms let you focus on creating content, while they handle the website upkeep and formatting. Additionally, these platforms have created communities of people with similar interests including people who are passionate about FOSS. At first I thought this would be the best solution. I wouldn’t need a website domain. I wouldn’t need to figure out how to host or where to host my blog. I wouldn’t need to focus any time on formatting or adjusting the look and features of the site. I would just practice technical writing. If I chose Medium it seemed like I would be a very small minnow in a huge ocean of content. As I examined the content on DEV my content didn’t seem to fit in with their focus on coding and development. Front Page Linux appeared at first to be the perfect fit, and it was already a part of an online Linux community that I loved. So I submitted my first post to Front Page Linux. This new platform was still figuring out their processes in receiving submissions, and my article got lost in a digital dust bunny.
Filled with excitement over my submission, I contemplated the next four articles. Because of my recent involvement in the MX Linux community, I realized that I wanted to write a series of articles about their new desktop offering, MX Fluxbox. In a new platform like Front Page Linux which has posted about 9 articles per month, I felt that my planned articles would put too much focus on one small part of the FOSS world that is covered by the creators of Front Page Linux. So if the platforms I evaluated weren’t the right fit, how would I host my own blog. Years ago, I had started a short lived blog on Wordpress.com . I could re brand that blog, and add a custom URL, but that would only accomplish my first goal, practicing technical writing. I had heard about static site generators, and I knew the names of a few of them. Every “beginner” article that I read about static site generators portrayed them as an easy way to create and manage a blog. A static site generator (or SSG) would help me accomplish the other two goals. When you use an SSG with GitHub Pages to deploy your blog, you use git commands with every post or change made to the website. A common SSG feature reads Markdown and transforms a post written in Markdown into a static HTML page. Since FOSS projects have transitioned to using Git repositories to manage their code and documentation contributions, deploying my blog on GitHub Pages just made sense. Although Fedora Docs have settled into using ASCIIDOC as their plain text formatting tool, there seems to be greater support in FOSS documentation projects for the use of Markdown as the preferred formatting tool. So it was settled. I would use a SSG with GitHub Pages, and I would begin working my way to accomplishing all three of my personal goals to become a better FOSS documentation contributor. Besides, it will be easy, so I thought.
I recently visited the Hugo’s discourse forum , and I noticed their greeting text for the new user. I wish I had read this honest and true piece of advice earlier.
Some Knowledge Required
Dare we say that while Hugo is indeed pretty magical, it is not meant to be a “magic wand” to suddenly give you a published website a la Square Space or Wordpress. You are expected to already know how to assemble a static web page, for which you do need some basic knowledge of HTML, CSS, command line and text editors. Or how to prepare a space to host your website. The bottom line is, if you are unwilling to invest the time required to learn these things, then Hugo is not for you.
That paragraph might have sent me back to resurrect my blog on Wordpress.com if I had read it before I got my first static site to build. In my simplicity, I thought that using an SSG would be an easy command line version of Wordpress, WIX , or Squarespace . I feel at home in the Linux terminal and using text editors. SSG’s speak the language of front end website developers. They use terms that make my head swim like: HTML templates, CSS properties, TOML, YAML, JSON, front mater, taxonomies, and SEO. If I had experience as a website programmer or designer, I believe that my learning curve in using an SSG would have been smooth instead of a sharp climb up a rock face.
I ran into trouble fast when I attempted to choose a theme other than the one suggested in the “Quick Start Guide.” The theme I picked needed dependencies installed from npm . My first test threw all sorts of errors relating to the theme and how I had configured it. I had no idea where to begin trouble shooting the errors. Thankfully the next theme worked without errors, so I have stuck with that one. The learning curve continued up the rock face this past week. I struggled to get a working RSS feed and favicon. If I had experience as a website developer, I believe that I would have grasped the concepts in the documentation and tutorials with less effort. So often I struggled to know if my issue was caused by my theme, a configuration mistake I had made, or because I had placed the file in the wrong directory in my SSG’s hierarchy.
Do you want to travel down this road of discovery? Don’t waste hours and days debating which SSG would be the best one for you. The FOSS world has given us a plethora of static site generators. Pick three or four that caught your attention, research them briefly, and then pick one and stick with it. Because GitHub Pages point to Jekyll in their documentation, I originally thought that I would just use Jekyll. Mistakenly, I thought that I could avoid a local install of Jekyll because I was using GitHub Pages to deploy my blog. When GitHub’s “Getting Started Guide” gave instructions for a local install of Jekyll, I reconsidered my options. Hugo seemed easier to install and maintain on both my MX Linux and Fedora systems. The Hugo documentation also seemed easier for me to understand as well. You might make a different choice, and that’s okay. Make your choice and start learning.
In the end, I have no regrets. Already in the first few weeks of maintaining this blog, I recognize my progress towards the three goals that I set. In keeping with those goals, I’m planning to devote this coming week to a deeper dive into learning how Hugo works. I plan to practice my technical writing with a new tutorial as well. I look forward to sharing my next discovery soon.
Image credits include the original picture of the climber by Simon Steinberger from Pixabay and the Hugo logo belongs to the Hugo Project .
