| layout | title |
|---|---|
default |
About |
This guide aims to provide a quick start in the field of technical writing for beginners. It employs various techniques mentioned in Andrew Etter's book Modern Technical writing. The content is split into two parts: the first part of the guide focuses on explaining Etter's recommendations for technical writers. While the latter offers concrete implementation of Etter's principles by providing instructions on hosting a resume on GitHub Pages using Static site generators like Jekyll.
-
Etter's book dedicates a large chunk of the book to the discussion of lightweight markup languages like markdown for technical writing. The idea behind the concept is simple, languages like markdown strip down the unnecessary complications related to working with markup languages like XML, HTML etc. to help the writer invest a greater time in polishing the content. Moreover, markdown is better for readability and does not even require knowledge of the syntax to make minor changes.
-
Etter's book highlights the importance of using a version control system like Git. It provides many benefits like providing a permanent storage space for your projects and documentations. It makes the process of tracking changes easy by allowing for multiple restore points and also the ability to create branches for experimenting with new features. Most importantly, it fosters collaboration among developers and other stakeholders. Etter highlights the importance of invlovement between the stakeholders to deliver a better experience for the end user. Moreover, such colloborations ensure the documentation remains up to date and relevant for the end users. As it creates a more open environment documentation for new errors and problems might be added as they spring along the way.
-
An important idea at the core of Etter's book is the simplification of the process of technical writing, to reduce the focus on building technologies to support the documentation and instead invest more time in perfecting the content. The idea is evident across the book as Etter recommends using simplified tools like markdown over traditional solutions. Similarly, instead of using complex hosting technologies and content management systems, Etter suggests the use of static site generator to build and host technical documentation.
Popular static site generators (SSG) like Jekyll is a popular choice for writing technical documentation. Jekyll is an open source static site generator based on Ruby and provides an excellent starting point for beginners. Static site generators reduce the headache of the developers to maintain complex client and server processes to host websites and instead provide a streamlined way for hosting websites for technical documentation.
GitHub fits the bill perfectly for building technical documentation. It is based on the popular distributed version control system Git at it's heart and has in built integration with Jekyll which highly simplifies the site generation process. At the same it also offers experienced users the freedom to configure the site to their needs. Lastly, it also provides a free website to host the content on.
Therefore, the guide will focus on using GitHub as a solution to host a resume written in markdown using the GitHub Pages feature and in line with the principles at the heart of Etter's book.
- Windows operating system
- Markdown editor like Visual Studio Code
- A resume formatted in Markdown
- Jekyll
- GitHub account
-
-
Create a new repository on your GitHub account.
-
Upload your resume as a markdown file and rename it to index.md.
-
Go to Settings > Pages page for your repository.
-
Navigate to Build and deployment.
-
Select Deploy from branch as the source and the desired branch (main is the default branch) and click save.
After completing the above steps, you should have the GitHub pages website up and running within a few minutes. You can navigate to your website by clicking Visit site button on Settings > Pages page.
-
-
-
Select a Jekyll theme you want to use for your resume, GitHub has list of supported themes to select from.
-
Create a _config.yml file in your GitHub repository.
-
Add this line to the config file,
theme: [theme-name]For example,
theme: minima -
Wait for GitHub to build the edited site and you should see the updated site with the theme applied.
Tip: Remote themes available on GitHub can also be added to the project using,
remote_theme: [user-name]/[repo]For example,
remote_theme: sharu725/online-cv -
GitHub's build tools work very well until they do not. Even in the best-case GitHub's site takes several minutes to show the changes, which may not be a big problem if you do not intend to make many changes on the website. However, the whole process starts to slow down the development time and in case GitHub's server is overwhelmed it can take significantly more time to complete the process. Therefore, setting up the process on a local machine makes the changes show up instantly and also offers a closer look at the processes which work inside the Jekyll website generation.
-
-
Make sure your system has the latest version of Jekyll installed. Refer to this guide for windows installation.
-
Clone the GitHub repository to your local machine.
-
Open a CMD on your machine and change directory to where the repository is located.
-
Execute the command below.
jekyll serve -
The website will be available at http://localhost:4000 on your browser.
-
At the end of these steps, you should have your own resume hosted on GitHub Pages. You can access my resume at https://arsh331.github.io/resume.
-
Markdown Tutorial: An easy-to-follow tutorial for learning markdown.
-
Jekyll Installation: Website features Jekyll installation for a variety of operating systems like macOS, Ubuntu and Windows.
-
Windows CMD Cheatsheet: Tutorial features common CMD commands useful for following along with this README.
-
How to terminate the Jekyll site locally?
Answer: You can terminate your Jekyll site process by pressing Ctrl + C.
-
Why is my website not showing up on the GitHub Pages page?
Answer: In case you cannot see your website, go to the Actions page on your repo. It should show your website under All workflows wait until the build is complete (a green mark is displayed) and try again.