Writing on the principles & practice of building digital products

Frontend.md

A command line tool which generates documentation for your existing frontend code in seconds.

Download Frontend.md on npm →

There's amazing work being done on web styleguides at the moment. They're being adopted all over the show, and the benefits of using them on larger projects are self-evident. However, many projects I work on are small, experimental, or otherwise don't justify a full styleguide, but nonetheless need some kind of structured documentation. I also know myself well enough that I probably won't write a readme for everything I work on. It's just not realistic.

So to that end I wanted to create a simple, automated way of generating documentation which is as portable and frictionless as possible. Something I could drop into any project and get a birds eye view of what's going on. This desire has manifested itself in Frontend.md - a simple way to generate documentation from your existing frontend code. Here's what it does:

  1. Looks through your Sass and Javascript and outputs a nested folder structure to a markdown file
  2. Pulls out the first written comment in the file and adds it next to the filename

Below is a screenshot of an example Frontend.md file, which you can see in all it's glory via the example on Github.

Frontend.md example screenshot

The indentation style I've used is heavily influenced by Hugo Giraudal's superb sass-guidelin.es project.

So far I've found using frontend.md to be a very interesting way of getting a new perspective on my code. Projects I work on today use very different technology and approaches to projects I worked on a year or two ago. It's the nature of the work, and one of the main reasons the web is so interesting. This also means that when I come back to look at old code it's often tough to know why on earth I did things the way I did. Using frontend.md on older projects has been a great way of getting my bearings.

An interesting side effect of running frontend.md on existing projects is that's it's become apparent how often I don't follow my own advice. Empty files, badly organised or uncommented code - it's all there. Seeing it all in front of me in black and white has been a pretty effective way of guilting me into doing something about it and fixing things as I go along, rather than just forgetting about it and thinking I'll come back to fix it later (which of course I never do). Having this visibility has been really helpful in making good structural decisions.

The project is very much in it's infancy, a fact further exacerbated by my novice status as a node developer. My hope is that with some hard work the project will grow and help more developers write better code.

Resources