Slashdot Mirror
What Makes a Good Design Document?
dnnrly asks: "I've been writing software professionaly for a couple of years now for more than 1 company and I've noticed a recurring pattern: I get put on a new project that already has a bit of history and I get told to read the design documents and then implement XYZ. What happens is I read the document, find that it gives me a lot of information about certain aspects of the system we are building, but leaves huge gaps in others. We're going to be rewriting some of the procedures very soon and I'll be able to influence the software side so I wanted to ask Slashdot readers what sort of things have they seen in design documents that they've liked/thought are a good idea? What have they found works and what doesn't? If all else fails, where's a good place to find all this stuff out?"
"There's usually a very defined and rigid format for every design document and the writers have obviously tried very hard to make sure that procedure has been followed, generally leading to an almost unreadable doc or a design for the sake of it. Part of the issue is that these guys have written the design after 2 or more years exposure to the problem so they tend to forget just how much they know."
Here's the classic article by Jack Reeves.
The Army reading list
The best design documents are ones that aren't trying as much to fit the cookie cutter as much as they clearly convey the idea of the design.
I'm not saying to throw design standards to the wind. I'm saying that your standard as a design document generator is to create something that is readable, decent to look at, and clearly conveys what is going on.
Try to use vernacular vocabulary and language style when explaining what things do, and try to make your pictures look as pleasing and simple as possible.
Hope that helps.
The primary problem is that there's too much information to document. I could create a document which included every design decision and every little facet of the project, but the document would wind up so huge, it'd be impossible to work with. The best resource I know of is the project guru. Every project has one -- the one guy who seems to know everything or at least can tell you where to find the details. Find this guy and pick his brain as much as you can. That'll carry you a lot farther than the documentation itself. However, if the guru is no longer around, you're up a creek without a paddle.
Summary:
This series of articles is about functional specifications, not technical specifications. People get these mixed up. I don't know if there's any standard terminology, but here's what I mean when I use these terms.
- 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.
When you design a product, inside and out, the most important thing is to nail down the user experience. What are the screens, how do they work, what do they do. Later, you worry about how to get from here to there. There's no use arguing about what programming language to use before you've decided what your product is going to do. In this series, I'm only talking about functional specifications."One of his books: Joel on software
His blog: What's a Spec?
Highly recommended!
I'm not totally sure what you mean by Design document, I've seen many software shops. Some call the requirements document design, while others define the design document as the document that describes the high level description of the internal architecture of the system (system diagram, major modules, client/server decomposition, class diagram).
Either way, I like to start with some templates I created based on IEEE standards, a few come to mind, Here's the list:
IEEE standards pertaining to sofware engineering. In particular take a look at the Software Requirement Specifications and the software design descriptions.
Some of these are very documentation intensive, but I find that at least reading through them when starting a new project helps me direct my thoughts and make sure I don't forget anything that might be relevant to the phase in question (what? I need to think about the maintainability? the stability? the robustness?) pick and choose those things that apply to your project.
Painless Functional Specifications--not precisely what you were looking for, but pretty close, I think.
. . . is a prototype.
Exactly!
But most 'old-school' outfits using heavy waterfall processes think that prototyping is evil if you do any of it prior to writing your 50 to 100 page 'design document' (I worked at a place like this a few years back).
Of course the company that uses Agile processes and encourages prototyping will probably get to market way before the dinosaur company.
You should read the entire series, but I'll give some of the highlights:
tS
Consider the daffodil. And while you're doing that, I'll be over here, looking through your stuff.
I will assume that the audience for the design documents is other programmers who have not worked on the project since its inception. With that in mind, the most useful design documents are:
1. Short. Hundreds of pages of detailed design are useless without context. Short documents can and should provide context and pointers to other documents (or code) that will explain the details. If the document is more than about six pages long, it will be ignored by most programmers.
2. One of many. It is obvious that you cannot describe a complex system in six pages. Try to write many design documents that are short. The documents can be a hierarchy. There should be a top level document, that refers to the individual elements that make up the system. Each element can be described in its own document. Each element's subelements can be described in their own documents, and so on, down to the lowest level that it is interesting to document.
3. Describe major functions and interfaces. The document should tell what the system (element or subelement) does, and where the reader can learn more about the elements that implement the functions and interfaces.
4. Describe things that don't change much. One of the problems (as noted by other posters) with most design documents is that they are not kept up-to-date. The solution is to write documents about things that don't change much, such as the overall system design and interfaces. And if the overall system design or interfaces do change, then you can usually persuade people to update the documents.
In my view, good software design documents provide context and pointers to the authoritative documentation. Most programmers (myself included) do not trust any documentation that is too detailed, since it is usually wrong.
I have to agree with the statement about traceability though. One of the worst things I've had to deal with is getting a specification document that does some stuff and then have to write the requirements "that would result in this design if we started with those requirements." This is endemic to all industries: ill-formed or ill-stated requirements. I'm always amazed at how many "requirements" are either designs or implementations or are not testable or aren't requirements at all. Even more entertaining are tests that don't test in a way that proves requirements are met...
If I had to enumerate what makes good design the list would have to include:
- DO NOT START DESIGN UNTIL YOU HAVE THE REQUIREMENTS (yes, I know there are exceptions, but you should at least have *most* of the requirements first).
- Have a good requirements document: everything is actually a requirement (not a design or implementation) and is testable (if you have the word "not" in it, it's not testable, for instance).
- Make sure the design is design and not implementation (design is "sum two numbers and check for overflow"; implementation is "temp32 = x16+y16; if temp32 > MAX16 then result16 = MAX16 else result16 = x16+y16;). Put another way, despite the popular writings I've seen lately to the contrary, CODE IS NOT DESIGN (any more than a car is the design of the car).
- Make sure you can test that THE DESIGN MEETS THE REQUIREMENTS (which is subtly different than "does the design do what I designed it to do?"). If the design doesn't satisfy the requirements, it can never be a "good design".
- Separation of responsibility. You mentioned XP above where "the designer is the coder is the tester" which is just bad practice in my experience. My company *strongly* discourages the designer to be the coder, or the coder to be the tester (the designer can be the tester though, and this often makes sense). This is because there are inevitable blinders that you put on when coding your own design or testing your own code.
Ok, that wasn't an exhaustive list by any means, but I think those are the key points. To summarise: have good requirements, separate requirements from design from implementation, and have many eyes looking at things throughout the whole process."There are a dozen opinions on a matter until you know the truth. Then there is only one." - CS Lewis (paraprhase)
I tend to use the 4+1 View Model, originally introduced in 1995 by Philippe Kruchten at Rational Software. It uses a set of different views, in order to clearly communicate a system's design (or architecture).
b rary/wi-arch11/?ca=dnt-65/
The 4 views are: Logical, Process, Physical, and Development. The +1 is the Use Case view, which describes the specific requirements that influenced the design.
I sometimes add a Data view and/or Security view. In any case, I use the 4+1 approach as a starting point and tailor it to the system at hand.
For more info: http://www-128.ibm.com/developerworks/wireless/li
Getting back to the original question, a design document should be divided into three primary sections. The first section should always say what the problem is that the design document is trying to address. Any given design document should address only a limited set of problems, or it will become too complex. Ideally, any given document should be small, compact and address one or (at most) two issues.
The second section should describe how to use the solution presented to solve the problem described. In programming terms, this is your API. That is all it should describe.
The third section should then cover how the solution goes about solving the problem. Again, that is all it should cover.
When projects or modules within those projects are updated, it should be possible to update/replace any one section in any one document without touching any other section or any other document.
Documentation should also always stick to the level for which it is intended. Ideally, references should be to ever-more specific information, never the other way round. So, a project overview might point to the components of that project. Each component might then point to documentation on the low-level mechanics. On the other hand, a discussion on low-level mechanics is not the right place to talk about a specific project that uses those mechanics. That gets in the way of understanding and obstructs code reuse.
That, I think, is the key to writing good documentation. Does it positively assist those who would need it? If the answer is "no", or is even a "not sure", then it doesn't matter what standards it follows, it is useless.
The ideal length for a document is going to vary, project to project, but by building documents in a modular fashion it should be rarely necessary to have a document longer than about 20 sides of A4. Most should be around 10 sides. Anything longer likely covers unrelated topics and can be split up. (Remember, it is easier to open 20 books to one page each, than to open one book to 20 different pages.)
This limit gives you about 3-7 sides per section per report. If you need more than 7 sides, the design is too complex and unmaintainable over the long-haul. On the other hand, any less than 3 sides likely means that the project has been over-designed with lots of redundancy, plenty of overhead and no possibility of meeting the requirements.
Going by this description, virtually all documentation in existance is ghastly beyond all imagining. Which, by and large, is exactly how most people see it.
It's a small world and it smells funny; I'd buy another if it wasn't for the money; Take back what I paid (SoM)
I write seperate functional specifications. If the implementation requires new machines and installation by our operations department, then I might do a presentation showing why we need it, and how to hook it up (for most things this is pretty much standard boilerplate) - and perhaps how to pay for it in an appendix to the spec.
The software design documentation is in the code in the form of a detailed comment at the begining of the main code module explaining my design choices for each piece. I like to use languages, such as Perl, that allow me to format and extract documentation directly from my source code. I also like it to be inside of the code so I can make changes to my documentation at the same time that I make changes to the code. This is much more efficient for me - things don't get lost in the shuffle.
Going forward my goal is to generate XML documentation for not only the design document, but also the user manual, and other documentation from the same source code. I'll have a makefile sitting in my revision control archive that will generate all of my documentation for all apps in one command. BAM! I'm done, and can then read and edit my docs at my leisure.
The hard part is getting everyone else who touches my code to follow the same procedures.
Lodragan Draoidh
The more you explain it, the more I don't understand it. - Mark Twain
Not all of these things will be appropriate for all systems. This is not a table of contents!
Know what you are trying to build; otherwise you won't know when you haven't managed to build it
or per group of web forms,
or per batch process
or per
In the case of MS Office, for example, the requirements for loading and saving documents has nothing to do with the requirements for handling macros, and none of the above has anything to do with the way that the GUI is structured.
All of these, then, should be separate in the documentation. They are separate in function, they are separate in nature, they should be presented as separate units, because that is what they are.
Keep doing that for the rest of MS Office and I guarantee you will find that you can document the entire of MS Office without any given unit of documentation exceeding 20 sides. 10 sides if it is designed well. (Although we know the answer to that one.
Documentation writers should be forced to learn EBNF and Jackson Structured Diagrams. Why? Because these force you to think in small pieces, to modularize and compartmentalize. If you don't, you'll go nuts. Besides, it should be possible to then take a JSD/EBNF description and map one simply-connected set of rules to one - and only one - document. One document should also map onto only a simply-connected set of rules, with no overlap.
In this case, it is not a "generalization", it is simply a direct consequence of structured programming techniques. Redundancy and Bloat Are Evil, Satanic and Despicable. Clean Designs Are The Only True Designs. Documentation is no different.
It's a small world and it smells funny; I'd buy another if it wasn't for the money; Take back what I paid (SoM)