Generating front-end documentation

In recent posts we have talked about what a front-end tool kit is, how we are using them, and why we feel they are important. Thus I thought I would share some of our experiences when using different tools so far.

To give a little background information, we currently use Grunt in our build process and have tried several tools that integrate into our workflow. Here is a brief overview of our experiences with various tools we have tried.

KSS

We used KSS to generate our front-end toolkit way back when the idea of front-end documentation was relatively new. KSS is a documentation specification and styleguide format. The format allows you to write documentation straight into your CSS or SCSS files, which would then generate our front-end toolkit.

We found this approach was easy to use and requires minimal maintenance once configured. It’s simplicity was both it’s strength and its weakness for us. It didn’t give us enough flexibility to create the documentation we needed. Complicated components could easily  take up over 100 lines of text at the start of your SCSS files. This was less than ideal for the kind of detailed documentation we provide.

Jekyll

We had used Jekyll several times in the past for static site generation and it worked well. It’s a mature static site generator that also works nicely for generating documentation.

Whilst a great tool, we soon found that it’s imposed file structure was not ideal for us. We wanted a modular file structure that allowed all files (HTML, CSS and JS) relating to a single “component” to live in the same folder. The structure imposed by Jekyll meant that it was not the right tool for the job.

Assemble

We used Assemble to create a front-end toolkit for a project where we needed detailed documentation that we couldn’t produce easily using KSS or Jekyll. Assemble’s flexible file structure and it’s relaxed use of layouts, pages and partials was exactly what we wanted.

As our project grew we started to discover that Assemble wasn’t quite as good as we first thought. As we added more pages, partials and data, we realised we were losing vital time as Assemble recompiled. This meant it became frustrating and time-consuming to work on the project and wasn’t how we wanted to work.

HarpJS

Recently, we have started using HarpJS as our tool of choice. It’s intended as a static web server with additional preprocessing features. Along with other benefits, its ability to process EJS files and separate data from templates makes it a great tool for creating our documentation.

It is flexible enough to allow us to use our preferred folder structure and allows us to keep our code base [DRY](Don’t Repeat Yourself). Presently, HarpJS ticks all the boxes and helps us to easily provide documentation for our front-end toolkits.

The future

Whilst HarpJS does everything we need it to now, it doesn’t mean we have found the perfect tool. Other tools such as Middleman, look promising and there’s no shortage of tools to choose from. The key for us was to find a tool that had an impartial folder structure and helped us to document our code with ease.

This is a rapidly changing landscape for front-end development and what works today might not work for us tomorrow. Our hope is that the tools we have chosen will not only help us but will also help anyone working with the code in the future.

If you would like Nomensa to help you with your website build please don’t hesitate to get in touch.

You can give us a call on +44 (0) 117 929 7333 or submit this short form. In the meantime, take a full look at the web development services that we offer.