documentation

Using Cookbook Documentation to Pass on Knowledge

Documentation is hard. Like writing code, it is a delicate balancing act of packing information into a format that is both very dense and very readable. Going too far in either direction severely limits its usefulness.

While ramping down a client project recently, I was asked to provide documentation and guides for the JavaScript application stack the company was using. Talking such a broad topic in a useful and consumable way was a daunting challenge. Read more on Using Cookbook Documentation to Pass on Knowledge…

Sticky Documentation, Part 2: Source Control History as Documentation

Last week, I introduced a concept I’m calling “sticky documentation” and reviewed a few ways that we can make the most of the “stickiest” documentation we have: the code. Today, I’d like to talk about another form of “sticky” documentation: source control history. Read more on Sticky Documentation, Part 2: Source Control History as Documentation…

Framework Docs Are a First-Class Citizen

Documentation is a crucial part of any good API or framework. Despite this importance, it often gets neglected and treated as an afterthought.

I recently asked another developer how he always managed to put together such well-thought-out and complete documentation. His response was: “Documentation Driven Design (DDD): if your API feels clunky to document, it’s probably a bad design.” This reminded me of my first introduction to Test Driven Development (TDD). By breaking your code into smaller chunks and testing them first, you were immediately placed on a road traveling toward better design. Given how useful TDD has been for me, DDD seems worthwhile.

One of the main considerations that determines whether I use a framework is how complete and easy to understand the documentation is. But in my own hypocritical way, I’ve neglected good documentation principles on my own hobby projects and frameworks. Read more on Framework Docs Are a First-Class Citizen…