20 May 2010 zanee   » (Journeyer)

Writing good documentation and presenting your work.

I'm going to make this short. Writing good documentation is extremely difficult which is why it rarely happens. When it does happen you get a readable article, book or column that reaches you in its intended fashion. Whether it be to teach or inform it is a practice to satisfy the readers hunger for which they are reading said article, book or column in the first place. So imparting with knowledge in a sane and coherent fashion is an art that I feel has simply been lost to convoluted grand-standing and the feeling that one should not have to "dumb-down" a topic in order to reach the reader. There is the argument that there are levels of scope in which one needs to have a full understanding before they can begin to understand the terminology. It's valid in some corner case where one would expect that understanding to already exist but if the documentation doesn't take that into account. It is not accessible and needs to be written again.

This is a problem specifically with science but more-so in regards to technical manuals and such. Some of the smartest people still have problems writing ACCESSIBLE documentation. So here are some guidelines you can follow to make your documentation more accessible so that it satisfies the hunger of your reader.

  1. Outline and detail every step no matter how mundane in as precisely a way as you can. (this involves a lot of work you may deem pointless like typing out the command cd /directory)
  2. If a topic needs another piece of documentation, prevent straying away from the main course of the documentation. It's safe to note that the topic you are referencing or referring to needs an adjoining piece of documentation or has another piece of documentation that is referenced in biblio or towards the end of said documentation.
  3. Your reader maybe your peer and you may suspect this peer is as avid and learned on a topic as you yourself are. This is not always the case so NO acronyms if you can help it. For example, referring to HyperText Transfer Protocol in it's full expanded verbiage every other paragraph helps.
  4. Concepts of terse knowledge should be kept short and simple. There shouldn't be copious amounts of detail before another paragraph or chapter. I see this a lot.
  5. You may need more than one book; don't try to fit everything in one book. Let your reader take a break.
  6. There is no such thing as DUMB-DOWN. There is such a thing as copious amounts of detail. As a reader, I prefer the copious amounts of detail, again, as precise as possible. If I already know what I'm looking at I'm free to skip over it, please don't determine that for me. Obviously I'll note that you don't need commentary such as "please turn the page" as that is just you being stupid.
  7. Do not waste your readers time. If they can't follow your steps or create a picture with the words that you are writing. You are doing it wrong.
  8. DO NOT LOOK TO YOUR PEERS FOR REVIEW FIRST. Hand your book or topic to someone who has absolutely no idea what you are discussing. If they can understand or at least halfway follow some of the more terse conceptual pockets; THEN hand it to your peers for review. If they can also understand it, you've done a good job.

None of the above is simple but if you follow some of these guidelines it will help you. I can guarantee at the very least that I will most likely have very little to say in regards to your documentation, article, book etc. Well, at least in regards to readability.

Now onto presenting your work. Lately, over the course of the last year. I've consistently seen people work hard, work on papers, work on research with the understanding at some point that this data, research and such will be presented to an audience. They do all the hard work, and then arrive to present 5 minutes before hand confident in their work. Only to have all sorts of niggling issue with projectors, laptops, etc. This seems to be almost a fad, at my place of employment, at research facilities, at school, at the library. I see it, over and over and over. The only time where I've seen a truly affected issue is when a project bulb blew and this gentleman was so prepared he had a pico-projector and just continued on. Every other issue could have been solved if the person showed up an hour or so before their presentation.

Having your peers sit around like idiots while you try and fiddle with a projector is INSULTING. It is the difference between a brilliant presentation and a mediocre one. It also affects you as the presenter when you are trying to fiddle about with frustration, anxiety and heaven forbid the lack of presentation or rescheduling due to hardware failures. Here are some guidelines in order to look like a king and have rounds of ovation in your name.

  1. Once you feel you are ready to present. Present infront of a crowd of 0. Walk through your presentation several times with yourself.
  2. Avoid Powerpoint except to display visual images and bullet points. If you are reading directly from PowerPoint then why are we having a presentation? Just send the PowerPoint file to everyone and don't waste the time.
  3. TEST the presentation where ever you plan to host or present. Check the room or auditorium out, ask about web cameras, microphones (wireless,wired), lighting etc. ALL of it is important
  4. Do the above AGAIN. Walk through it all yourself if you have to
  5. Arrive EARLY to your presentation. I don't care who you plan to present to or for. Be there early.
  7. Treat your audience to a show of all your hard work. Bask in the glow of the ovation.. Answer 2-3 questions. Take off the suit tie and go home.

If you follow the above guidelines I can assure you that you will have a great presentation. Where things seemingly run smoothly to the audience. Little did they know you spent many a hour crafting your presentation specifically for them. At the very least I can guarantee that if you hold future presentations you won't look like an idiot infront of your audience; or at the very very least, you won't look like an idiot infront of me.


Syndicated 2010-05-20 17:07:22 from Christopher Warner » Advogato

Latest blog entries     Older blog entries

New Advogato Features

New HTML Parser: The long-awaited libxml2 based HTML parser code is live. It needs further work but already handles most markup better than the original parser.

Keep up with the latest Advogato features by reading the Advogato status blog.

If you're a C programmer with some spare time, take a look at the mod_virgule project page and help us with one of the tasks on the ToDo list!