Automating Documentation Workflow With GitHub Actions

Documentation is an essential part of any software project. It helps users understand how to use your software, provides context for development, and can be a valuable resource for future work. However, keeping documentation up to date can be a challenge, especially as projects grow and change. This is where automation can help. In this article, we'll explore how to automate documentation workflows with GitHub Actions.

The Importance of Code Documentation

Documentation is an essential part of software development. It involves describing how your code works, what it does, and how to use it. While many developers may feel that documentation is an unnecessary extra step in the development process, there are several compelling reasons why you should care about code documentation.

Let’s go over a few reasons why code documentation is important.

1. Proper documentation helps ensure that your code is maintainable. As your codebase grows and changes over time, it becomes increasingly difficult to remember how different parts of your code work. Documentation helps you and the team understand the purpose and functionality of your code, making it easier to update and maintain.
2. Secondly, documentation can make it easier for others to contribute to your codebase. When new developers join your project, they need to be able to quickly understand how your code works and how to use it. Good documentation can provide this information, making it easier for new developers to get up to speed and start contributing.
3. It can also help you catch errors and bugs in your code as development progresses. In writing good documentation, you are forced to think through the purpose and functionality of your code in a more systematic way, which can help you identify inconsistencies or issues in your code. Avoiding bugs and errors before they become bigger problems.
4. Finally, good documentation can make your code more accessible to others. By providing clear, concise documentation, you make it easier for people with different backgrounds and levels of experience to understand and use your code. This can help you build a more diverse and inclusive development community, which can ultimately lead to better software.

Check out a comprehensive style guide for writing technical documentation from Microsoft and Google.

What is GitHub Actions?

GitHub Actions is a feature from GitHub that allows you to automate workflows directly within your repository for continuous integration or continuous delivery. These actions ate event-driven, and you can create custom workflows that trigger based on certain events, such as a push to your repository or the creation of a pull request. These workflows are defined using YAML files and can include a variety of actions that run commands, perform tasks, and interact with other services.

Automating your Documentation with GitHub Actions

Before we proceed with the automation workflows, you need to decide if you want your docs to be hosted or not. You can choose to host your docs with static site generators like Jekyll, Hugo, and MkDocs. With Jekyll, create a configuration file that specifies your site's settings and options. This file is called _config.yml. 

Here's an example configuration file:

In the sample above, there’s a title and description of our site, as well as specified a theme to use. You'll also need to create your pages using Markdown or HTML files. For Jekyll, these files are typically placed in a _pages directory.

Committing Your Documentation Files

Once you've set up your documentation site, you'll need to commit your files to your GitHub repository. This will allow your workflow to access and build your documentation site. Make sure that your files are organized in a way that makes sense for your site generator, and that any dependencies or plugins are included in your repository.

Creating a Workflow

Now that your documentation site is set up and your files are committed, you're ready to create your GitHub Actions workflow. Workflows are defined using YAML files that are placed in a .github/workflows directory in your repository. Here's an example workflow file for Jekyll:

Let's break down this workflow file step by step:

• name: A descriptive name for your workflow.

• on: The events that trigger your workflow. In this case, we're triggering any push to the main branch.

• jobs: One or more jobs that define the steps to be taken.

• build-and-deploy: The name of our job.

• runs-on: The environment in which our job runs. In this case, we're using the latest version of Ubuntu.

• steps: The individual steps to be taken

Using Linters

When it comes to writing documentation, it's easy to focus on the content itself and forget about the importance of formatting and consistency. However, consistent formatting and style are critical for readability, maintainability, and collaboration. This is where linters come in.

Linters are tools that automatically check your code for common errors and formatting inconsistencies. They can help you catch mistakes and ensure that your code is consistent and readable. In the context of code documentation, linters can be used to enforce consistent formatting and style across your documentation, making it easier to read and understand.

For this article, we’ll be using Vale linter, Vale Linter is a popular linter tool for checking and improving the quality of written content, including code documentation. Vale uses customizable rules to check written content against specific style and grammar guidelines, making it easier to maintain consistent and high-quality documentation.

Vale can be used with various markup languages, including Markdown, reStructuredText, AsciiDoc, and more. It can also integrate with popular text editors and development environments, such as VS Code and Sublime Text, allowing you to catch errors and style inconsistencies in real time as you write. Vale offers support for custom styles and style guides. You can create your custom style guide, or use one of the many pre-made style guides available in the Vale Style Repository. This allows you to enforce specific style and grammar rules that are tailored to your organization or project.

• Create a directory locally on your computer:

• We will keep all our GitHub actions in the .workflows folder. After creating a workflow directory, proceed to create a new file vale.yml inside the workflow folder.

• Copy the code below and paste it into your vale.yml file

name: Is a string that is given to the workflow being setup

Jobs: actionable events that are to be executed. An environment is also selected where the actions are to run. In this case, we used Ubuntu.

Setting Up Vale on our GitHub Action

It’s time to set up our vale workflow on the GitHub action we have created. 

Copy the following into your GitHub action.

Here’s a list of recommended style guides to use, but in our case, we made use of the write-good style guide.

• Setup vale Configuration File:

• Every commit on your markdown document triggers the vale action on GitHub.

In conclusion, code documentation is an essential part of software development that can help ensure maintainability, improve collaboration, catch errors and bugs, and make your code more accessible to others. While it may take some extra time and effort to write good documentation, the benefits are well worth it in the long run.

However, simply switching using GitHub Actions sometimes might not be enough to get the best out of your project space, an engineering analytics tool can equip you with the data-driven insights you need to place your team on top. Hatica offers metrics across 13 dashboards, powered by CI/CD tools, Jira, GitHub, and GitLab. By collating tool activities at one place, Hatica helps teams streamline their workflow and improve productivity.

Subscribe to the Hatica blog today to read more about unblocking developers, and boosting productivity with engineering analytics.