What makes simple documentation
Friday, 15 July 2011 04:32
What makes simple documentation? Our technical writing team is asking itself this question at the moment. We’re also asking our product managers to give us examples of simple documentation, and counter examples of documents that could be made simpler. I interviewed my first PM on this topic this week: Dave O’Flynn, product manager for integration at Atlassian. His answer was so neat, concise and helpful that I decided to blog about it.
Firstly, I was impressed with the way Dave quickly and unobtrusively rephrased my question. I asked him:
How would you define simple documentation and do you have some examples of simple docs?
Dave’s reply was:
The Dragons documentation is the best of example of a complex problem explained simply.
Neat. A self-documenting reply!
Secondly, it’s cool that Dave chose the Dragon Slayer documentation as his example. Dave sat back, put his hands behind his head and gave a concise list of points about what makes those documents simple:
- They are bite-sized.
- The language is clear and simple.
- They are consistent.
- The reader starts at the top and reads down. There are no links that force the reader to branch off to other documents and then come back again.
- Each page gives you a goal, then tells you at the end what you have succeeded in doing.
That’s a very useful list. One of our team members has already applied these points to a new set of documentation she is designing. I’m looking forward to more feedback from our product managers and team members. And I’m wondering, does anyone else have any ideas about what makes a simple document?
Read more http://ffeathers.wordpress.com/2011/07/15/what-makes-simple-documentation/
