Really good post on writing your read-me first

Found that writing user manual first was very helpful for writing the sugar api for Brainstorm realtime 3d engine: http://cleverplugs.com/sugar/

Oddly I ended up writing api methods that seemed unlikely to be used other than for a learner trying out the engine. However they made the learning process much easier (and encourage console/command-line usage).