Thursday, February 14, 2008

An art called Smart Documentation

There is no denying the fact that if there is one aspect of software engineering that gets the least importance, then it is documentation. No wonder that thoughtful people tend to advocate it all the more. We, then, in our exuberance, barf out pages and pages of text, which, even we would not have read, had it been spewed by another.

Be informed, that no software, either product or project requires end-to-end documentation. It is going to be shelved anyway. What any software needs, is a smart document. And, all a smart document will need, is a smart YOU.

I list out a few points below. Follow them at your own risk [ You wouldn't want to be called smart. Would you now? ;o) ]

  • Know your audience.
    The first thing is to know whom you are targetting with your document. Is it the techie geeks within the organization; then code and design snippets would do. Is it a bunch of freshers; then you may have to allow them to soak in the details rather than throw jargon at them. Is it the business people; then be sure to outline information that needs their buy-in. If it is a bunch of dunderheads; then don't even bother; for they don't even care.
    Know that, no one document is suited for all people. It would be advisable to serve up different documents for different segments of people; rather than have it all in one single document.

  • The scope
    The questions you have to constantly ask yourself is - Is the item I am writing necessary in the overall context?
    Know the scope of your document and stay within the limits of it.

  • blah! blah! zzz!!!!
    In technical documents, always try to avoid long paragraphs with huge lines of text. This will do no good than to put the reader to sleep. Always look to have details put in point-wise lists. It is always easier to register 5 points with 2 lines each, than a paragraph with 20 lines.

  • A picture can speak a thousand words.
    Use pictorial diagrams liberally within the document. You will be surprised at what a simple flow chart can get through to your audience than carefully worded text.

  • Hand sketches.
    So now you know you have to have diagrams in your document. So that means you have to master MS Paint & Visio??? Good, if you do. If not, then just draw up a sketch with a pencil, scan and attach. The idea, is to get the message across; not to impress.

  • Granularity.
    The level of granularity you go within a document is again based on your target audience. Do not burden the reader (and yourself) with unnecessary information. Stay short; be sweet; and to-the-point.

  • Index
    The Document Index is one of the most important parts of your document. It gives a bird's eye-view to the reader of the content; and will also enable the reader to move to the required section swiftly.

  • Indent
    Try not to have more than 2 indent levels in your document. Make sure there is minimal white space visible, and indents bring in white space.

  • Use fonts wisely.
    It is always easier on the eyes if the text is consistent throughout the document. So,
    • try not to colorize text.
    • try not to have variable font-sizing within a paragraph of text.
    • try to draw reader attention using italics and bold.
    • try to use fonts relevant to the document. Arial is always a better choice over ComicSansMS for professional documents.

To end, a point to ponder!!! More often than not, lengthy documentation (or) creating a lengthy document gives one the notion of contributing/working a lot. Beware that you do not fall into the trap of false thinking. Though documentation is a good-to-have activity in any organization, false documentation only leads to productivity degradation of the individual.