Code Walkthrough (in progress)
Working software over comprehensive documentation
When some coworkers and I started on a fresh agile team about ten years ago, this principle resonated with us. “Documentation? What a waste of time! It’s always out-of-date. It’s usually hidden somewhere where no one can find it. We’ll just check the code, when we have questions, anyway. Down with the Word docs!”
To be clear: I still agree with the last part, wholeheartedly.
How did it turn out? We got away with not writing documentation while we were a stable, three-developer team for a few years. It was going well. Then, we needed to expand our team rapidly. Then, we experienced some turnover. In these cases, the lack of documentation was a painful gap that had to be filled with one-on-one training from other knowledgeable team members.
Were we wrong about documentation? Most of our observations were correct, but we drew the wrong conclusion. We also conflated project and design documentation with system documentation—documentation about a system to be built versus one that you are actively maintaining. It all got lumped together as “documentation”, and we ignored it.
I now see documentation as a valuable asset, but writing good documentation remains as hard as ever. To restate some of our objections from earlier:
- It’s useless if nobody knows it exists.
- If it exists, can anyone find it?
- It is difficult to organize. Related: Does it allow you to learn the right thing at the right time?
- It becomes out-of-date as soon as it’s written.
- If all other conditions are met, will anyone actually read it?
I now take these as challenges to write better documentation rather than abandoning it, altogether. How to overcome these have been percolating in the back of my mind over the last few years.
Idea: The code walkthrough
One form of documentation that could be useful when onboarding new people to your team or to a specific project is developer documentation about the project. It should cover the background the person needs to jump in and start coding. This could include things like prerequisites (tech stack and skills), project structure, key design decisions, patterns used, and primary features or functions.
Some of this is well-suited for regular text documents—I’m partial to markdown on Github or Github pages. Some of this content would be more naturally covered in a guided walkthrough by an expert. That’s where I started toying with the idea of a code walkthrough format for documentation. What if the documentation walked you through the code like your tech lead would?
I made a prototype for this, and I’ve been polishing it up to a spot where it’s almost usable.
This could be an engaging and approachable way to introduce someone to a codebase or to walk them through an important pattern. It draws attention to the most significant elements in the code and can help tie them together. While you could communicate the same information with a more traditional text document, this would immerse the reader in the context: they can track which file is open and where it is located; they can see the entire file along with the highlighted section.
It helps with the will anyone read it and some of the organizational challenges of documentation. But with something this elaborate, won’t it get stale immediately? That’s coming next!
Tech stack
So far, this is built with
- vanilla HTML, CS, and JavaScript
- Prism.js for syntax highlighting