Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??
Bravo on bringing Joel's work here. I've been reading his stuff for a while.

First, I think we need to define the difference between Functional and Technical specification. I'll have to agree with joel here in his definitions, and I'll just re-iterate them for those that didn't read:

  • A functional specification describes how a product will work entirely from the user's perspective. It doesn't care how the thing is implemented. It talks about features. It specifies screens, menus, dialogs, and so on.
  • A technical specification describes the internal implementation of the program. It talks about data structures, relational database models, choice of programming languages and tools, algorithms, etc.

That being said, on with your questions.

1.) How detailed do your specs have to be?

As detailed as you can make them. You need to realize that both types of specifications are living, breathing documents. Changes in one are reflected in the other, and vice-versa. In my opinion, your technical specifications should eventually get down to the prototyping level for functions and methods. Most of these will have a described interface that the programming team agrees on. Who ever is developing it isn't nailed down to anything specific as long as it meets the interface requirements (subject to code review, of course).

As the code and these different interfaces mature, you will find different sections of the specifications being redefined to reflect these ideas and lessons learned. You might realize that an object structure that you were going to rely on wasn't going to cut it, and you might have to redefine the structure, and scrap that piece (or at least small pieces) of the specification. Don't sweat it, redefine. It will make for a stronger end result.

2.) How do you start writing them?

One technique that I use is to find each piece of functionality defined in the functional spec, and rephrase them as the question: "How would I?". Start accumulating your answers to these questions, and you should start to see your objects, as well as your application flow, take shape. Much of the basic shell is going to be described in the func spec, especially if someone was keen enough to use a UML, or screenshots, pictures, pencil drawings, etc.

3.) Do you get a general outline or do you go over each task as they come up?

Well, you'll need a general outline of the tasks that you know about. Keep in mind that you'll be adding to that outline as those tasks begin to get defined in more detail based on what has come before, and new tasks are discovered.

C-.


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



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others chilling in the Monastery: (4)
As of 2024-03-29 02:06 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found