Thursday, April 18, 2013

Writing documentation

When working on a project, creating tools or methods, it is of tremendous importance to write documentation. But this task itself is not straightforward. Really! Think of a topic that you know much about: your job, or your favorite hobby... then open a page in a text editor and try to write 1 page of documentation for it! Maybe just half a page! Good luck with that!

What I have found to work for me when creating a documentation, is putting myself in the shoes of someone who knows nothing. I generally think about this person as an "idiot". It shouldn't be considered insulting, though. The idiot is me, before I knew anything on the subject I'm writing documentation for. That way, I can create documentation that is easily understandable by anybody, without prerequisites.

What will the documentation look like, in the end? Probably a mix of screen captures and short sentences. The simpler (for the reader), the better.

No comments:

Post a Comment

Creative Commons License
Erik Lallemand's blog by Erik Lallemand is licensed under
a Creative Commons Attribution 3.0 Unported License.