How detailed do your specs have to be?

That depends greatly on who the target audience for the spec is.

A rule of thumb I use is to make the specs sufficiently detailed that someone one notch less skilled than I am could read the spec and have a good chance at implementing whatever the spec describes. As a rule of thumb, it's worked pretty well.

Two book recommendations to help make your specs readable:

  1. Lyn Dupre, Bugs in Writing (Revised). Dupre is a technical editor who has handled a number of heavyweight technical authors (Patrick Henry Winston, Carver Mead). She has a great ear for the patterns of mistakes that technical folk tend to make.
  2. Joseph Williams, Style: Toward Clarity and Grace. Unlike teachers who focus attention strictly on sentence structure, Williams shows how to link sentences together into a readable whole that will draw a reader onward. A friend TA'd for Williams at U. Chicago, and has great stories about how Williams would take some piece of recent bureacratic nonsense and iteratively refine it into something readable. Williams doesn't directly address technical writing, though everything he talks about applies. Williams also delights in tying strict grammarians in knots with counterexamples.

In reply to Re: How to write technical specs by dws
in thread How to write technical specs ? by dwiz

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.