Hey dwiz,
I'm going through the exact same thing at work right now, and am creating my first technical design/requirements document for software that I'll be implementing. Some tips that I've gotten from fellow developers is to start out with a set of well-defined use cases that sum up the problem to be addressed by your software. Each use case may describe the functionality of a single function or method or it might describe the interaction of an entire subsystem. That's up to you.

The idea is that by describing the whole of the problem in non-technical language you not only allow yourself to more tightly define the scope of your task, but you also provide a good starting place for someone else who might have to pick up where you left off.

As a plus, by fully spec'ing out your project with a bunch of use cases, you've essentially defined what your code will have to do and all you have to do is program to the spec. This is a lot easier than programming the code and then making a spec that matches what your code does.

In reply to Re: How to write technical specs ? by CubicSpline
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.