← Back to Blog Home

Framework Docs Are a First-Class Citizen

Development Practices
by: Shawn Anderson

Article summary

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.

Gamebox documentation

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.

Non-DDD approach

My usual workflow for Gamebox looks like:

  1. Doodle the design on paper or whiteboard.
  2. Write example code usage, usually in a game I’m working on.
  3. Test-drive the code.
  4. Go back a year later and try to document what I did for a release.

The problems are evident when I need to visit code to see how something works. If the documentation doesn’t help me enough, how could it possibly help the new person trying to learn your framework?

DDD approach

I’m going to try a small experiment for future features in Gamebox:

  1. Doodle idea.
  2. Code example and place in high-level docs.
  3. Document overview and the rest of the planned API for this feature.
  4. Test-drive the code.

I’m confident that forcing myself to document before writing the code will be much easier that trying to play catch-up come release time. I’m still not sure why it’s so hard to eat my own dog food on side projects, but, I’m learning… slowly. I now try to pair when possible, write acceptance and unit tests, and write good documentation for side projects. It takes more time, but the results are well worth it.

Here are a few documentation ideas / tools:

 

Related Posts