Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery
 
PerlMonks  

How to write technical specs ?

by dwiz (Pilgrim)
on Oct 12, 2001 at 08:11 UTC ( #118408=perlmeditation: print w/ replies, xml ) Need Help??

Greetings fellow monks,

I thought this was more a general programming question than a Perl one. I have been reading this brilliant article on functional program specs. Doing what he says to do there has made my life a heap easier.

BUT.....

I don't know how to write good technical specs.
I have tried writing out what I want my program to do. That does help. I feel as though I am missing something though.

My questions are:
How detailed do your specs have to be?
e.g.(Do you plan every sub?)

How do you start writing them?
Do you get a general outline or do you go over each task as they come up?

I have tried super search for past nodes on this but have come up empty.
Any insights, links or books that would help to start writing good technical specs would be greatly appreciated

-dwiz

Comment on How to write technical specs ?
Re: How to write technical specs
by Starky (Chaplain) on Oct 12, 2001 at 09:48 UTC
    The answer to your question would occupy volumes. But hopefully I can give you some good pointers.

    First off, a good technical spec starts with a good nontechnical spec. I would recommend a book on Use Cases. Your biggest battle will be to convince nontechnical people around you to produce specifications that lend themselves to a good technical specification. Take the challenge on as you would any good technical problem: Evangelize, inform, educate, and push them to do what makes your life easier. Induce them in any way that you can to produce use cases in conformance with a use case template that you find useful.

    Secondly, I would adopt an OO approach to coding. This not only has advantages insofar as it improves your coding abstraction, but there are a gajillions tools available to software engineers who adopt the OO approach. Read a book on UML. I've found "Using UML: Software Engineering with Objects and Components" by Perdita Stevens to be a good introductory text. If you don't use some commercial product like Object Domain or the (in my opinion overpriced) Rational Rose in the workplace, try Dia, an excellent open source UML modeling tool. Also consult other sources of engineering knowledge, such as the "Gang of Four" book on design patterns.

    Finally, I would be patient. Absorb as much as you can. Continue to familiarize yourself with proper techniques as you develop in your career. But recognize that the ability to write a good technical spec comes as much if not more from experience than from textbook knowledge. You may find that you only apply a fraction of what you learn in the workplace depending on such things as time and resource constraints. But you have to learn it all in some capacity to know which fraction to apply.

    Hope this helps :-)

Re: How to write technical specs
by dws (Chancellor) on Oct 12, 2001 at 09:53 UTC
    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.
Re: How to write technical specs ?
by CubicSpline (Friar) on Oct 12, 2001 at 17:09 UTC
    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.

Re: How to write technical specs ?
by greywolf (Priest) on Oct 12, 2001 at 20:07 UTC
    I like to start by simply writing down what a user will need to do and in what order.

    I start with a list of everything that will appear on a given screen, basically a screenshot in plain text. This will tell you what has to happen before the screen loads (pull customer info, pull past transactions etc).

    Next I make a list of all the options(actions) the user will have (write sale to db, conduct search etc).

    At this point I can start figuring out the basic flow of the program and what functions I will need. Notice that through all of this I have not done anything technical. Now I should have enough info to start creating a technical spec for any language I need to work with.

    Sometimes this will seem like an over simplified approach but it can expose some basic design issues/assumptions that I might not have thought of right away.

    mr greywolf
Re: How to write technical specs ?
by MadraghRua (Vicar) on Oct 12, 2001 at 22:28 UTC
    We are writing for an audience that doesn't know how to code but does know what it wants - I suppose its the same every where, really. So we have divided the process up into three parts documentation wise:
    1. Overview document - this addresses the overall goal of what the software is to do, how it will do it, what type of resources will be needed to support it, etc. its meant to be a high level overvieew readable by Managers and other techie types ;)
    2. Funtional Requirements Document - here we detail use cases, functional response of the software, pseudocode and table structures, if necessary. This is a more low level typs of document designed for users with a reasonable level of computer experience. It has enough information in summary sections to allow pointy haired bosses to read it and have a clue while detailing nitty gritty details for detailed analysis. This step normally has anough info to allow us to build a model or prototype of the code for users to evaluate functionality and see what is missing.
    3. End Documentation - actual documentation to go with the finished product. It has class descriptions, schema ERDs, and user/admin manual type of docs. It is meant to be pretty comprehensive.
    For designing systems, I'm reading through UML Toolkit by Ericksson and Penker, Wiley Press. I seem to remember a doc from Sun that spoke about making readable documents but I forget the actual reference, sorry.

    MadraghRua
    yet another biologist hacking perl....

Re: How to write technical specs ?
by dws (Chancellor) on Oct 12, 2001 at 22:30 UTC
    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.

Re: How to write technical specs ?
by cacharbe (Curate) on Oct 12, 2001 at 23:32 UTC
    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-.

      Ya, i agree with your writings, we should differentiate the functional and technical documents. And need to document the system overview,work-flow with diagrams(Its all based on how you want the document either in a overall or in-depth manner)

      Santhosh Kumar R.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://118408]
Approved by root
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others drinking their drinks and smoking their pipes about the Monastery: (6)
As of 2014-08-01 03:30 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite superfluous repetitious redundant duplicative phrase is:









    Results (256 votes), past polls