Part one of a series on redesigning and building our internal documentation site.

• Part One: Overview (you are reading it)
• Part Two: Why Eleventy (coming soon)
• Part Three: Customising Eleventy (coming soon)
• Part Four: Using Netlify and the Netlify CMS (coming soon)
• Part Five: The design and front-end process - designing in the browser (coming soon)

One of the things all organisations should have is a set of guidelines and policies governing conditions of work. In addition, every software company requires clear documentation on development processes such as quality assurance, agile, security, front-end guidelines, preferred architecture and so on. In 2015 we decided to make all of these transparent and accessible via a website, rather than a motley collection of documents sitting on a drive somewhere. Moving to this system had great benefits as it was easy to update, created an always available repository of documents and served as an invaluable onboarding tool.

Initial requirements

As the site had to be updated regularly, and by developers and non-developers alike, the first requirement was for a CMS.

We weighed up the following options:

• Build it ourselves: While this meant having complete control over the code base it wasn’t the best option as it would require constant maintenance and we did not have the capacity for the extra work.
• WordPress: Equally loved and despised, WordPress is a well-established option for this kind of site but was not suitable for our needs as we would have to maintain a MYSQL database, PHP and so on. The benefits of WordPress’ content editing capabilities were outweighed by the maintenance required. There was also the small problem of not a single person in the company having any experience with PHP!
• Ghost: In looking for alternatives we came across the fledging Ghost project. Ghost offered an easy to use CMS (in Markdown with preview), user management, and a front-end that was relatively easy to configure as it is all written in JavaScript. As the NML site runs on Azure we were able to quickly configure a sub-domain and install Ghost on the same platform.

Once we had made the decision to go with Ghost we had the site up and running in no time with various sections for all our internal documents, ranging from onboarding processes to housekeeping, working policies, developer and QA guidelines and some additional touches like a list of birthdays and a welcome message to new joiners from the CEO and COO.

Moving on

While Ghost served us well (it even became known as the “Ghost site”) it was not without its issues. Updating versions was a manual process, tagging was incoherent, mail from the server required additional configuration and so on.

In 2018 we finally made a move from Ghost to Jekyll, the static site generator developed and maintained by Github for their static pages and documentation. We had been using Jekyll internally for a number of years to build style guides (now what we would call a design system) and to run the NML website. It was the obvious choice for updating the documents site and was a platform the front-end team were well-versed in.

Of course, we still needed some form of CMS. There are a number of options for running a CMS with a static site generator. I won’t go into all of them but there’s a comprehensive overview available at headlessCMS

The obvious choice for us was Netlify CMS as we had already used it for a client’s static site. The front-end dev who had worked on that project took on the build and in no time we had ported the documents site to Netlify, running the Netlify CMS with continuous deployment via Github and Netlify’s Github Gateway. Netlify offers user management and authentication out of the box so we had no issues setting up editors and publishers via the CMS workflow.

Recently however we have moved away from Jekyll as our choice for building design systems and static sites. As more and more of our front-ends are built in React a tool like Storybook offers a living design system for re-usable UI components, something a static system doesn’t allow. Other issues with Jekyll is its slow time to compile and it becomes hard to manage deep hierarchies within a site. It’s also difficult to maintain the Ruby environment required for Jekyll and we found ourselves having to do all sorts of time-consuming updates and fixes to keep it in good shape.

So while the documents site served its purpose running on Jekyll/Netlify CMS it was time for an upgrade. Not least because the design hadn’t been changed since 2015 and it was showing its age. After much consideration of the current crop of static site generators (and there are a lot of them!) we decided on Eleventy.

In the next post in this series I will run through the reasons for our choice of Eleventy and show you how to get it up and running.