Part V. The Documentation Pillar
Let’s face it: our frontend code is getting more and more complex with every project we start. I’m not saying this is a bad thing, it’s just that this rapid rate of growth comes with its own set of growing pains.
Just a few years ago all of our CSS was written in a single file, and each style used a long complex selector to find just the right element on the page to modify. If we found that this style was interfering with something else on our site, we just wrote another line of CSS at the bottom of the file with a longer selector.
In the same way, our JavaScript file was written using a bunch of jQuery functions targeting preexisting markup and applying some functionality to it. Each function would contain every bit of logic and processing required to get the job done. If we needed to write a slightly modified version of this functionality for another element, it was always easier to just duplicate the code, change the selector, and update the logic.
We were writing the equivalent of a single-file PHP application for every project.
Then, just as new PHP developers are taught to break up their code into small reusable objects and to organize their code into individual files, our frontend projects started to look less like a cascade of instructions and more like a complex system of abstraction, dependencies, and interfaces. But while we were quick to incorporate the object-oriented, multi-file approach of traditional programing languages, we were very slow to adapt their dedication to documentation.
We’d spent so many years living with highly declarative systems that we simply defaulted to keeping our understanding of these new systems locked away in our heads. Getting this information out of heads and into documentation won’t be an easy transition, but the time lost from not having documentation outweighs the time it would have taken to write it. As the proverb goes, the palest ink is better than the best memory.
What Is Documentation?
Documentation is the blueprint of our design system. Without it, we will inevitably create solutions for problems that have already been solved and spend large amounts of time sifting through code to find the simplest answer. Without documentation, we leave our new hires scratching their heads as they wonder who could ever get work done in this system.
As we look back over all of the architecture we’ve established to this point, it would be criminal not to spend an equal amount of time planning our approach to documenting it. Documentation is part of development, not something to do after the important work is completed. Just like bloated code that needs refactoring, inefficient processes that could be automated, or functionality with no test coverage, skipping documentation creates technical debt.
Don’t assume that documentation is simply writing down how things work. Yes, we need to establish time within our development process to document the things that we are building, but documentation is so much more than just writing a paragraph for each line of code we write.
Documentation comes in many forms, and many of those forms don’t occur without some architectural intervention. While some documentation is just static text describing each function we write, it often has a build system behind it that layers on search, navigation, and visual presentation. Other documentation is used to display system assets, driven by the styles, scripts, templates, and schemas we are writing.
Static Documentation
Hologram is a Ruby-based general documentation tool. It allows you to make small documentation entries all throughout your codebase, then it gathers them into a single static website. These Markdown-formatted documentation blocks can be placed right into your Sass, CSS, or JavaScript files. They are sprinkled with metadata that describes page name and navigation information, and they are a free-form space to write. Hologram allows your documentation to be inline with the code you are writing. This helps keep the documentation fresh and always in view of the developers.
SassDoc is a Node-based system documentation tool that claims to be “to Sass what JSDoc is to JavaScript,” and it delivers! SassDoc is similar to Hologram in that it relies on inline blocks of comments to drive the finished documentation site. But where Hologram is very generic and multipurpose, SassDoc is focused on describing all of your Sass variables, functions, and mixins, and how they interconnect and depend upon each other. If you are building a large Sass framework, or creating a complex grid or color system, then SassDoc is the tool you’ll want to pull out.
Code-Driven Documentation
Pattern Lab is a multiplatform Pattern Library tool that allows you to develop your design system in a modular approach and converts your templates and CSS into a browsable library of patterns. In modular design systems, you create each unique piece of the system once, and then combine them to create more complex patterns. Pattern Lab gives you a framework to build out those smaller pieces and combine them into complex patterns or even fully fleshed-out pages. This browsable component inventory is the perfect tool for developers, designers, UX, QA, and product owners to gather around. It creates a common language and common reference point for every piece of the design system.
JSON schema is a language for describing your data format, as well as a specification upon which you can validate your data. In the realm of frontend architecture, we can use JSON schema to document the data that each of our templates or patterns is expecting. A JSON hyper-schema can also be used to describe the various methods in which we can interface with our design system over HTTP, including validating, rendering, and testing. JSON schemas are code-driven documentation because they serve a functional purpose of validation and driving editor tools. Schemas also produce a very readable set of system specifications, replacing what is typically a large amount of handwritten instructions that developers would otherwise need to implement a feature.