By clicking “Accept”, you agree to the storing of cookies on your device to enhance site navigation, analyze site usage, and assist in our marketing efforts. View our Cookie Policy and Privacy Policy for more information.
PreferencesDenyAccept
HomeArticles
How Arundo Switched to Docs as Code

How Arundo Switched to Docs as Code

How Arundo Switched to Docs as Code

Arundo wanted to develop a publishing process enabling people across the company to contribute to docs by keeping costs down and use as many of our existing tools as possible.

As the leader of the Arundo documentation team, I was recently given the challenge of developing a publishing process that enables people across our company to contribute to docs. I was also required to keep costs down and use as many of our existing tools as possible. This was an exciting challenge and one that we solved by switching to a Docs as Code philosophy.

WHAT IS DOCS AS CODE?

Docs as Code is all about writing and publishing documentation with the same tools that developers use to build software. Content is written in markdown using a text editor and then stored in a repository where it can be reviewed by peers. Once approved, the content is built into a website using a static site generator and deployed to a web host by an automated process.

IMPLEMENTING DOCS AS CODE

All of this sounded fantastic to me and after researching some of the tools necessary to implement Docs as Code, I knew that we could leverage our existing GitHub project to store content and handle reviews.

GitHub-repo-for-the-Arundo-Edge-Help-Center

I then found a perfect theme for us to use for our docs, MkDocs-Material, which uses Google’s Material Design approach, the same philosophy we use for our apps. Here’s an example of the theme used on our Arundo Edge Help Center:

Arundo-Edge-Help-Center

An added bonus was that this theme is designed for use with the MkDocs static site generator, which is a very fast and easy-to-use.

Excited at all of the momentum, I met with our DevOps team and found that we could use Travis CI to set up automation to deploy content from GitHub to Kubernetes. From there we could make our docs available on the web and accessible to everyone or restricted to certain users.

BENEFITS

So as you can see, we were able to solve our challenge by leveraging a lot of the tools and expertise we currently had available. Docs as Code has worked brilliantly for us and continues to provide the following important benefits:

  • Reduced costs - We were already using GitHub, Travis CI, and Kubernetes so we didn’t have to pay any extra to use these tools for our docs. Plus, our doc theme was downloaded for free and the MkDocs static site generator also costs nothing to run. The only real cost was some time to up my skills but that didn’t take long and I became an expert pretty quickly working with Docs as Code on a daily basis.
  • Increased collaboration - We now have people in all departments across the world contributing to our docs. Within a few minutes, anyone can get up and running on a doc project. We are also able to track content updates and handle doc reviews seamlessly through pull requests, saving the need to use any third-party tools for reviewing.
  • Seamless publishing workflow - We can merge content updates and through the power of automation, have them deployed to the web in minutes with no manual steps necessary. Writers don’t need to be DevOps engineers to push out updates but DevOps engineers can be writers if they want!
  • Flexibility - Our doc theme is open-source and highly customizable, so I can update the theme myself to meet our needs. I can make most of the necessary customizations myself but if I get stuck, I know I can bend the ear of a friendly developer to help me out.

SUMMARY

Docs as Code has been a game changer for us and revolutionized the way we produce documentation by making things easier. Instead of writing everything myself, I now have people from across the company willing to step in and write content, and reviewing content updates is quick and easy.

If you are curious but hesitant about using the Docs as Code approach, give it a shot. You will be amazed at what it can do for you and your team.

Related articles

Show all articles
Building an Industrial AI Companion using Arundo Foundation

Building an Industrial AI Companion using Arundo Foundation

While large language models (LLMs) may struggle to generate insights directly from time-series data, their strong pattern-recognition capabilities make them well-suited for identifying and synthesizing already existing insights. We therefore argue that an architecture featuring a separate graph-based domain model and time-series data storage is the ideal architecture for a generalized AI companion serving the heavy asset industry: An agentic AI can first identify relevant nodes (assets, sensors, and a large variety of pre-computed models) for answering a user prompt using a mixture of APIs, query language generation, semantic search, and graph traversal. Only after this filtering step is time-series data accessed and retrieved to synthesize an answer.
Revolutionizing Heavy Asset Maintenance: The Power of LLM-based Virtual Assistants

Revolutionizing Heavy Asset Maintenance: The Power of LLM-based Virtual Assistants

How Large Language Models (LLMs) can power virtual maintenance assistants for enhanced equipment issue diagnosis and root-cause analysis.
Navigating Sustainability: The Path to Scope 3 Emissions Management for Maritime Leaders

Navigating Sustainability: The Path to Scope 3 Emissions Management for Maritime Leaders

In the race to combat climate change, the maritime industry stands at a pivotal crossroads. As one of the most energy-efficient modes of transport, maritime shipping is crucial to the global economy, yet it remains a significant and growing source of greenhouse gas (GHG) emissions.