Documenting Interfaces

Many of the projects I have worked on revolve around writing. A lot of text has been written even before the first shape has been drawn or coded. On bigger projects I rely on keeping notes, asking questions, writing specifications—whatever is needed to better understand how something should work.

Interface inventories are great: they are not only helpful in keeping the consistency across the site, but they also help in creating a solid design system. If you are working on smaller or medium-sized projects, you might not have the resources or the time to create an elaborate interface inventory, but every little bit helps. Start by noting down different components you will need on the project as a simple list. This will get you into modular mindset from the start.

Use Structure To Your Advantage

I find it helpful to just pop open a spreadsheet and start writing down components. This helps me to better understand both the project, and the different components I need to take into account while creating a full page or a workflow. Some are obvious (header, footers etc.) but others are project specific—if you are building an e-commerce site you will need: filters, product listing, product view, galleries, reviews etc.

Why not think ahead and note them from the start?Sure, you will have to design each one of them, but a single spreadsheet is often easier to scan than dozens of prototypes or design pages. Your interface inventory is also a good starting point for discussion among the team.

There are several important benefits of documenting your interface inventory in a spreadsheet:

  • Grouping and semantics—we can easily group elements by type or by function.
  • Naming conventions—it’s easier to define a meaningful naming pattern when everything is in one place.
  • Discussion—even a basic interface inventory can drive others in your team to contribute, talk, discuss, suggest.
  • Simplification—complex interfaces can be simplified (and easier to understand) when they are broken down to smaller components.

Since I’m a big fan of workflow optimisation, I got the idea of reusing a basic interface inventory as a starting point for projects. I would usually write down the following: component name, file name, file type (*.scss, *.html etc.) and a description.


Files are generated automatically based on interface inventory in CSV format.

I got tired of creating all of these files manually and wanted a quick way to generate them all at once so I asked my friend Nikola to help me out. He wrote a simple Python script that generates a folder with placeholder files based on my interface inventory. Check out interface inventory repository on GitHub. The script helps you out by converting your interface inventory into files you can easily copy and paste into your project.

How Can We Improve This Approach

There are other ideas we could use to improve and simplify the workflow even more:

  • Prefill files with basic placeholder code based on file type and name (code snippets might do the trick)
  • Create basic style.scss with included files based on groups (like a project boilerplate)
  • Indicate which components rely on third–party components (e.g. Slick slider for carousels or Magnific popup for modals)

By keeping things simple we can apply this approach to all projects that are built with modularity in mind while providing extra value to the team and clients. It’s as easy and fast as writing notes.For large projects, this approach might turn out to be overly simplistic. For agencies and freelancers, however, it might speed up development and showcase the necessity of modular design.

What are your experiences with documenting interfaces? Let’s discuss on Twitter.