Friday, January 06, 2006

Teaching and documenting

Technically they are the same thing, whenever you are documenting something you are teaching a future student something. I haven't given that last sentence a great deal of thought so I cannot say for sure if it holds true in all situations however I firmly believe it to be true. Whenever I write documenation I think about the future person reading my document. I choose the language in the document based on who I think will most benefit from the document. I take documentation writing very seriously because documentaion should at it's very least transfer some knowledge from the author(teacher) to the reader (student). Many people including myself hate doing documenation for various reasons that run the gammit from ego (I'm a programmer not a document writer) to blank page syndrome (Where do I begin?). Because of the hate for the work I'm sure little or no effort ever goes into producing documentation properly.

In my daily job I am called upon to read and interpret other people's documentation as well as write my own documentation. What I have learned is that documentation, well to put it blatantly, sucks in general. I get so frustrated with so many document writers because they write the documentation from their own perspective. The author already understands the subject at hand and makes many assumptions about the reader's understanding of the subject. My personal expierence tells me; make no assumptions. I will avoid any tacky clich├ęs here but you can understand why.

I'm currently working my way through a rather large and boring set of technical documents for interfacing disparate systems together over the internet. This is old hat stuff for me I have interfaced systems together with the best of them. The problem with this set of documents is that they completely leave out any form of examples and simply give reference information only. I will make another statement, if a picture is worth a thousand words, then an example is worth 40 hours of boring trial and error interface coding. Now this documentation will work great for me once I figure out the basic skeleton of the communication structure. Give me the basic or minimum structure necessary so that I can at least make basic connections then let me know how to tweak the options so that I get the output I am looking for. What frustrates me more is when I call the authors of the documentation and ask questions I simply get "It's printed in the documentation". I'm sure all of the data is there but because of the poor structure and lack of examples, it is simply data and not information.

This page is powered by Blogger. Isn't yours?