A standard document structure for designing software

Question

I am looking for something like this: http://en.wikipedia.org/wiki/Software_design_document

But in more detail and also if something is an actual standard like ieee or iso?

For my requirements, I use Volere template.

Thanks, Zahid

Answer 1

Microsoft has a bunch of templates and links: http://msdn.microsoft.com/en-us/teamsystem/aa718795.aspx

More specifically, you might like the MSF3.0 doc templates which are pretty decent: http://www.microsoft.com/downloads/details.aspx?FamilyId=9D2016AD-6F8A-47F5-84FA-BEC389DB18C1&displaylang=en

If you want a standard, CMMI is implemented by MSF4.0 but you need to implement the TFS product to get it. The product automates loads of management tasks and makes implementation of CMMI cheaper.

As for ISO, all I ever saw from this is wads of big fat manuals used by auditors. They basically come and check that if you say you wrote a document that you actually do have a document, without really caring about the content. LOL!

The only other document templates I've used come with a methodology and are proprietary , i.e you have to pay. ex: Rational Unified Process (RUP) -- now owned by IBM.

Answer 2

Software engineering strongly suggests to use a (formal is better) modeling language to design software.

A well-known standard, for this purpose, is Unified Modeling Language (UML). Despite it is entered somewhat in common usage (at least some subsets of it, especially for object-oriented design) it is not without its critics.

I my opinion its worst aspect is (was? I am not up-to-date with version 2) that it lacks a formal semantics, so one don't know how to interpret precisely an UML design specification (there have been some attempts to retrofit a formal semantics on it, but, to my knowledge, without much success - with the possible exception of Executable UML).

I only mention here so-called formal methods (with their formal notations), which allow to reason rigorously about design specifications, because even a superficial treatment would require a rather lengthy discussion.

Update: if it is not clear, I am not advocating vanilla UML here. I mentioned it because I see it is increasingly (at least partially) used. In particular, as I wrote above, without a formal semantics, such "documentation" is more a burden, to keep correctly in sync with source code, than an asset.

A modeling language with a formal semantics, instead, can be used non only to reason rigorously (mathematically) about your design (has it such and such desirable properties? Does it avoid such behavior? Of course, not everything is verifiable/checkable statically - before the program run) but even to generate correct code automatically.

This seems possible with Executable UML (see this book site: Executable UML - A Foundation for Model-Driven Architecture). But, again, I don't particularly like UML notations, so this will not be my first choice.

Answer 3

Both of those are good answers, but I am going to have to ask how long your particular piece of string is.

I have created document templates for a few companies that did not have them, but those were all embedded telecoms projects. Even within the same project applications such as 'phone book had different needs from protocol stack (which communicates with the network), and that was different from device drivers.

Sure, there was a lot of commonality: architecture, interfaces, major data structures, etc. But some subsystems had a GUI, or not, threading, or not, time-criticality, or not, etc.

And embedded telecoms projects probably need different docs from Windows apps, which have different design needs than games, web apps, security systems, process control, etc, etc.

I'm not sure if UML would be the right tool for C, as opposed to C++ (not saying you can't use it, though).

So - how long is your particular piece of string? I strongly advocate document templates, but if you pick a one size fits all projects solution, you might meet opposition to adopting it if it does not seen relevant.

My advice is to study a bunch then roll your own.