Several years back in a talk about rapid prototyping with Smalltalk, of all things, Kent Beck gave out some advice on technical writing that stayed with me. He recommended targeting a single type of audience, rather than trying to speak to several. He argued that if you are writing consistently for one type of audience, others audiences can adjust, but if you skip between target audiences, you risk making everyone seasick.

To help keep yourself on target, Beck recommended that before you start to write, you first write out a short description of an ideal member of your target audience. Who are they? What do they do? What problems do they have? How will reading what you're about to write help them? Then keep this description in front of you (or within quick reach) while writing, and refer to it whenever you're in doubt about how to address a topic.

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.