February 2015

Download 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 - 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 file, which you can see in all it's glory via the example on Github. example screenshot

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

So far I've found using 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 on older projects has been a great way of getting my bearings.

An interesting side effect of running 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.


Ever wish you got more email?

Neither do I. You're busy, and so is your inbox. I'll only be in touch when I publish something new. And of course it goes without saying your email will be kept completely private.