Beefy Boxes and Bandwidth Generously Provided by pair Networks
laziness, impatience, and hubris

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
Specifications can have a way of taking on a life of their own, chewing up resources both to write and argue about them, and to keep them updated. Finding the right balance can be tricky, particularly when there are non-designing, non-coding "process" people in the mix.

I've found that it helps to clearly distinguish two types of specifications:

External specifications talk about externally visible aspects of the system. These specs serve as an interface between the development team and other stakeholders, such as documentation and QA. Getting these as close to right as possible on a large project is important. The trick is to put as little effort into getting them there as you can, since the process can a time vampire.

The type of external specification that I've gotten the most mileage out of over the past few projects has been Use Cases that describe concrete interactions between a user and the system. Uses Cases give the customer an early chance to say "yeah, that's how it's supposed to work" or "no, that's not the way we do things." And once the customer has signed off, they're a good customer proxy to have when a customer isn't available to talk with.

One thing I've seen projects skip doing when writing external specifications, to their eventual dismay, is to include a list of what the product won't do. A negative specification is a good way to keep Sales and Marketing in check! And you avoid some messy battles of the "you said you were going to do X!", "no I didn't!" type.

Internal specifications talk about what goes on under the hood. The conundrum here is that while most people say they need more in the way of internal specifications, most of what's produced (in my experience) has a short shelf-life, and little long-term value. The lasting internal non-code artifacts are typically diagrams: A one- or two-page object model, an interaction diagram, a decorated database schema. Other documents, unless they're close to the code, tend to drift off towards the bottom shelf or the back of some desk drawer. So, draw pictures.

Since the final authority is always code, keeping internal specs as close to code as possible can be a win. A lot of Perl code gets this right by using POD, which is easy to extract it into HTML for on-line specifications. Judicious use of javadoc is a win if you're working there. On my current project, we write PODs and javadoc as part of the design process.

In reply to Re: Benefits of the Specification by dws
in thread Benefits of the Specification by Lexicon

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, 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, 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.
  • Log In?

    What's my password?
    Create A New User
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others rifling through the Monastery: (7)
    As of 2020-04-08 18:32 GMT
    Find Nodes?
      Voting Booth?
      The most amusing oxymoron is:

      Results (45 votes). Check out past polls.