Weekly Journal 25 - Design Documents, Helix


This week I spent some time reading about lightweight software design documents, and tried out the Helix text editor.

Design Documents

At work, we are getting into building internal DevOps tools. To help communicate the requirements and context to the team, I have been looking at building some lightweight design documents. Traditional, enterprise IT design documents can be hundreds of pages of details that rarely resemble the final output, and nobody actually reads the entire thing. An alternative is a design document that outlines the context, goals and explored tradeoffs, without getting too far into the weeds with the technical details.

Malte Ubl has some very nice blog posts about how design documents are used at Google. The first is aptly named, Design Docs at Google, and it gives a great overview of the structure and what kinds of information should be in a design document. The second is Design docs - a design doc which is an annotated walk-through of a design document created using the structure outlined in the first post.


I stumbled over a link to the Helix editor on social media. It bills itself as a “post-modern” editor, in a similar vein to Neovim. It has some interesting ideas, including native support for multi-selection, but at this point it is still a bit immature to use as a daily driver. I think I will keep an eye on this project, and I am interested to see how it develops and matures. Maybe someday it will replace my trusty copy of VS Code?

What’s Next?

Still trying to work on my iptables automation project.