Even a chimp can write code

Saturday, July 23, 2005

On writing

I've written previously about how a sound project plan lends to a successful project. The past 4 months have given me some good lessons on program management. In this post I'll talk in stream of consciousness mode about things I now know. The main focus here is on effective writing.

Projects live and die by their vision. You must know why and what you are building and for what customer. This ethic can be stretched to fit any part of your job function, especially your writing.

Prepare. I cannot overstate that. Read lots of books, articles and technical papers. Get a well rounded view; the big picture. Analyze things constantly. Ask questions. The effort you put into your research will show in the quality of your output.

Be open, humble and respectful. Use other peoples' experience. Trace ideas to sources. Respect people for their ideas. Engage them early and often. Keep them involved in your process. If not actively, at least keep them up-to-date on the status. For a smooth ride, get buy-in from important decision makers, preferably even before the spec is baked.

Whatever your role in a project, insist on getting the spec right before the code is written. The spec'ing process may take several iterations, so plan accordingly. It is easy to view a spec as an unnecessary intrusion of process. If you can make and solve your mistakes in the spec, you won't have to do them in your code. We all know the costs involved in refactoring later on in the cycle.

Write your thoughts. Writing offloads it from your brain and lends to further elaboration and clarification. Break things down. Ideas are often complex and need to be explained lucidly. You can write eloquent prose or you can make lists. It pays to make lists. Many good PMs I have seen in Microsoft use this approach. They love their bulleted lists!

Give your audience a clear understanding of things you are presenting. If you are talking work items, always specify the cost.

Keep it simple. Don't go for eloquent prose. Set a bar: don't use a word unless you know its exact meaning.

Start paragraphs with the main points. This helps readers skim through your document and yet get the gist. Keep your document consistent. Be it in style or content. Stick to your core talking points.

Pay attention to language. Use fewer words. And fewer still if you are drafting a presentation slide deck. Be concise in your sentences. Don't use unnecessary phrases. Prune the redundant words. Use "although" instead of "regardless of the fact that" and "each" instead of "each and every" and "if" in place of "in the event that". Take my word; just omit the phrase "as a matter of fact". It means nothing.

Start small and work your way upStart your documents as a draft, maybe even a list of points. Then work your way up. Don't worry about spelling, grammar and formatting in your draft. Once your content is organized, edit mercilessly, improving with every iteration. One of the best investments I ever made was in buying "Elements of style", William Strunk's 1918 masterpiece. Things have improved now that I have Ashley: she's a great guide. But for a guy who spoke English only as a third language (after Tulu and Hindi), I needed all the help I could get!

Writing a summary at the top of the document is never a bad idea. By doing that you are being mindful of peoples' time. If the summary spurs their interest, they will read on. If not, oh well, at least you didn't waste their time. Also mention clearly what type of document this is: a Product Vision document or Functional Specification or Technical Specification or Design Document.

Use spellcheck, er, spell check.

Deal with ambiguity both in your job and in your writings. Refrain from making ambiguous statements. If, in your writings, you have to call something out but are uncertain how it pans out, flag it as such. For example, thanks to Henry, I use a style for 'Issues' in my documents. They serve as buckets for half-baked thoughts that wouldn't otherwise belong in the document. The revision process irons them out. They should never make it to the final version. If there are items in your 'Issues' or 'To do' list that will take less than 5 minutes to resolve, then resolve them now. Send that email asking for clarification. Call or walk to that person's office seeking an answer.

Once you have your document ready, distribute it for review. Seek feedback and when you get it, either incorporate it in your document or reply to your reviewer with the reasons you cannot. Using your best judgement on confidentiality of the documents, make it a point to post them to a site or forum or file share so your team and partner teams can readily access it.


Email this | Bookmark this


  • Thank you for a very good post. I write quite a few specs for a living, and have even decided to write a bit about it (see URL below if interested)

    Are there any particular functional specification outlines (templates) you use? There's several ways to address a spec's decomposition (by end-user use cases, by functionality area, businesswise, etc.)

    By Anonymous Kamen, at July 30, 2005 at 11:30 AM  

  • Kamen, I have a skeleton for the spec I like to follow, but I try not to limit myself to it. Here's what it looks like:
    <Spec Title>

    Author: <name>
    Document: <document type>
    Status: [Just started | Draft | Reviewed | Stable]
    Revision: <#>

    <Table of contents>

    1 Introduction
    1.1 Feature Abstract
    1.2 Document

    2 Design Document Issues
    2.1 Work Items
    2.2 Open Issues

    3 Scenarios

    4 Problem Statement

    5 Goals and Justification

    6 Functional Details

    7 API Details
    7.1 Summary
    7.2 Fields
    7.3 Properties
    7.4 Events
    7.5 Methods

    8 Supporting Type Details

    9 Design Time Support

    10 Security

    11 Globalization & Localization Details

    12 Accessibility

    13 Performance

    14 Versioning

    15 Appendix

    16 Document History

    Apart from the boilerplate header styles, I have styles for Issues, Code Samples, Inline Code Fragments and To Do Items. Although not in the spec category, the MS Office templates page has some useful resources.

    By Blogger Ashish, at July 31, 2005 at 8:11 AM  

  • Whenever I start to write my research papers, I try to keep things organized first. I read every available resource both in the internet and the book in the library.

    By Anonymous Research Papers, at February 2, 2009 at 5:06 PM  

Post a Comment | Home | Inference: my personal blog