Developing Programmers .com

This week I have spent most of my time writing documentation as quickly as I can for the job I am leaving.

They already have up to date API documentation etc, but they need more insights into the “big picture” of the software components and what the major ideas are in there without getting bogged down with details.

To help achieve this I’ve been scanning pages from my project notebook (yes, this is a physical book in which I write notes and draw sketches). I’m interleaving these scans with text in the wiki documentation for the project.

Scanning hand-drawn images is helping productivity impressively: I don’t have to get out the drawing software and make it look nice. I can add written notes around each page to explain how it fits in and add any references, links etc that I need. The style of the result reminds me a little of Powerpoint presentations, with the diagrams each followed by notes on what I’d want to say about each page.

Next time you have a great idea that you don’t have time to write up properly, consider taking whatever you have (even if it’s a diagram sketched on a satay-stained napkin at a restaurant) and throw it on the scanner. It’s better to have hand drawn images up on the internal documentation web site than missing documentation