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
Dee..zin...dok...u...ment...?
Figure out which class from your local university deals with software engineering, find the book(s) for the class, and buy it.
Writing a good design doc is mostly tedious work interspersed with lots and lots of communication with your programmers and customer.
-Erwos
Plausible conjecture should not be misrepresented as proof positive.
The design document was rumored to be a cross between a unicorn and the dodo bird. What would a bird need with a big pointy horn on it's head? I don't know, but then, I've never seen one of these rumored documents, so I can't say for sure.
Be sure your DD includes:
- Sitemap (web) or screen map (desktop app)
- Feature matrix with columns for features, rows for pages/screens and indicators where a page/screen has a feature.
- Detailed feature specs need to be written kinda like function documentation - "preconditions" that state what is expected as in the user is authenticated or the DB has products and "post conditions" that say what gets set or hwat the user can do.
- Style documents greated by graphics designers who understand the medium (web/Windows API/etc) are invaluable for refering back to when someone doesn't like a font size.
All this documenting is no fun, but it is more fun then dealing with the lake of the document.
I only came here to do two things; kick some ass, and drink some beer...looks like we're almost out of beer.
I document software for end users, and get some of my information in the early stages of development from design docs. I have to say that the most useful design documents that I've seen are ones that contain diagrams, flowcharts, and other "pictures" of how the system (or the module, component, whatnot) functions.
If I have to choose between a 50-page design document and three pages of clear diagrams, I'd pick the pictures.
Interested in a Flash-based MAME front end? Visit mame.danzbb.com
Basic communications 101 says the purpose of any document is to communicate. And you, the poor schmoe left with maintenance, is exactly the guy the design doc is supposed to be talking to. Now a lot of times businesses create documents just to "check off the boxes" in which case they want some big, heavy monstrosity to deliver. If that's what you're getting, good luck. People (especially programmers) tend to think of design docs as some kind of ultimate bible in the sky that's going to answer all questions and be a completely accurate guide to what's in the code. That's fine in theory, but in the real world the best design doc you're going to find is one that tells you what the design team was thinking when they started down the path of building this program. What's the patterns that were used? What constraints kept them from doing things differently? It's just a technical memo from them to you that's supposed to help you get oriented and work more efficiently. Sometimes those memos aren't done so well. My advice is to get what general information you can from them, and then talk to the coders who worked on the project. That's my two cents.
1. Write a design document containing information about the design document you're trying to create.
2. Read the design document you wrote in (1) describing the design document that you are trying to write.
3. Write actual design document as described in design document written in (2).
An Indian-American Hindu committed to non-violent thought/speech/action alarmed by the global explosion of radical Islam
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 net will not be what we demand, but what we make it. Build it well.
. . . is a prototype.
To be honest, I find that customers have a hard time visualizing how something will work unless they can interact with it. I'll take some internal design notes for myself, then whip up something and reiterate.
This approach doesn't work well with some projects, but for the small web applications I make it works great.
Existence.
At least for most of the projects I've worked on.
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!
... the "this is how it really works" document. That's what you're really interested in. There's nothing wrong with the design documents you've seen.
No, I'm not kidding.
The design documents which have driven you mad probably weren't incomplete. They were probably quite complete design documents. But a complete design document isn't supposed to cover everything. If you had a design document that was fully specified in every significant detail, you could run the design document through a compiler and generate your code. (This isn't as far-fetched as it sounds; there are tools to automatically generate large amounts of code just from simple UML diagrams. That's an example of design documents being translated directly into running code.)
A design document can best be viewed as the development team's prejudices regarding the best way to solve the problem. There will be holes in the design document, mostly in those areas where the programming team doesn't really have a good grasp on what the best thing to do is.
A good design document is a like a good steak; they're best when served a little bit rare. You want to give the guy who comes after you a game plan, but you don't want to commit yourself to doing things in one particular way when you don't know if that one particular way is going to work. After all, once the design document has had every stakeholder sign off on it, going back to the drawing board and saying "uh, this isn't going to work, let's try something else" means all the stakeholders get back on board again. But if the design document has some room to move--what you think are "holes"--then that gives the programmers freedom to get the job done without having to go through the entire design approval bureaucracy again.
Most serious software engineering shops worship at the altar of requirements and architecture documents. Hackers in the trenches add the "this is how it really works" document to that list. There's nothing quite as valuable as stumbling across some prior hacker's notes when you're trying to grok the system.
Stop looking at the design document for the 'missing' stuff. It might very well have been deliberately omitted. Start asking around for the "this is how it really works" documentation, instead.
Amen. I do Quality Assurance (and for those who don't know, that isn't just testing). I use design docs to figure out how something is supposed to work before I get it. Pictures are good. You can (intentionally) bury information in a 50 page document. It is hard to bury information in pictures. I say "intentionally" above because in the past I worked with a guy who was the director of a development group. He didn't like to design things, or tell people about how things were going to work. So his requirements and design documents were vast containers of information. His standard answer to questions was: It's in the document.
Me: What is the flow of events from beginning to end?
Him: It is in the document.
Me: I couldn't find it. Where is it?
Him: It's in there, you just have to find it. See, here on page 3, and on page 10, and...ummm... You just have to piece the information together, but it is all in there.
Talk about information hiding. In meetings, people would ask questions, and he would say "It's all in the document, should I go get it?" Nobody wanted to spend meeting time sifting through it for answers. And sometimes, the answers weren't there, and we would always get the "I'll add it". Of course, nobody ever checked to make sure he added it.
I fought for months to get him to add a flow diagram in a doc. He kept insisting that all the information was there and that a diagram was useless. After months and months, he finally added it. The FIRST thing that someone said at the next meeting was how useful that diagram was, and they pointed out some improvements to it. It turned out those comments sparked conversations that led to the discovery of flaws that went unnoticed for months. I'll leave it up to the reader to guess who got credit for the diagram in the document. (hint: Senior QA person or director of development)
Let me re-iterate: pictures are good.
My beliefs do not require that you agree with them.
Much of software engineering is received wisdom. It involves little engineering and even less science.
I draw the analogy to medicine in the 19th century because at that time physicians were finally trying to investigate the causes of disease and developing insight that, more than a century later, would lead to their interventions improving rather than diminishing life expectency.
Nobody knows what "best practice" should be, yet we're codifying a process. The design document is one aspect of this process. Rarely is the purpose of a design document to convey design. Rather, it is a "deliverable" presented to a PHB or client as evidence of progress. To this end, the larger and prettier it is, the better.
RFCs are requirements documents, not design documents.
An RFC specifies what behavior MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, MAY NOT exist. It doesn't say jack about how that behavior is supposed to come into being. I could write an OpenPGP application that did all of its work by hiring Bruce Schneier to manually do the RSA computations, and it'd pass the RFC.
RFCs aren't design documents. RFCs specify behavior; design documents specify how that behavior is achieved.
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.
Design Docs tell the reader how you intend to build something. In many shops (depending on the SDLC version, if any, that they use), it has little value after the design review.
As a roving consultant, I've seen a lot of crappy documents and SDLC (et.al.) procedures, and what has the greatest value for the programmers who come later is a Maintenance document that specifies:
1. The overall philosophy of the design: Why specific design choices were made.
2. What things did you want to implement (and why) but were postponed to a later version.
3. What design decisions were specifically rejected (and the reason).
4. Where are the system's weaknesses?
5. What are the coding standards specific to this particular project?
The Maintenance Doc provides guidance to the people who have to work on this stuff after you're gone (and to you, unless your memory is perfect). More than anything else, they will need to know the why of the design, not the what.
In my perfect world, the maintenance doc would be the main appendix to the design doc.
However, in most shops, the SDLC & its policies & procedures will prohibit that, and usually acknowledge neither the existance nor desirability of a Software Maintenance Document.
Good Luck.
There is not nearly enough love in the world, but there is far too much trust.
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)
The single biggest mistake most design documents make is that they document the design.
That's nice, to a small extent, but generally of relatively little use.
It falls down completely when
- the designer made bad assumptions that subsequently don't hold
- the users change the requirements
- someone actually writes the system
- the system goes through years of maintenance
So what is of use in these circumstances? The ideas, concepts, approaches and general thrust of the design.
Where did this design come from? Why has this approach been taken. What are the concepts embodied here?
Don't tell me that the Widget is round and talks to the Doodah.
Tell me _why_ the Widget is round (and why square wans't good enough), explain what the Doodah does and why the Widget needs to talk to it, what the contract (informal or formal) between the two is.
If the Doodah works with hexagonal Thingamies then explain that. If there aren't any Thingamies yet but it's possible they may be added give the guidance on where they'll be added.
A good piece of software design is a vision, a pure and beautiful concept in the mind of its creator. What gets written on paper has to share that vision with others, so that they can understand it, and share it going forwards.
Then you have design documentation that makes sense, that outlives the initial implementation, that's useful to people in years to come.
~Cederic
- Talk to the various stakeholders. Hold meetings. Get everyone's input on what's the Right Thing To Do.
- To the degree these ideas are not the Wrong Thing, do them, even if they're less efficient than you'd like, or are less fun to code. You're going to be giving them a prostate exam with a cheese grater in a couple of steps, so soothe their egos proactively by letting their ideas make it into the final product.
- Take the draft to your dev team. Circulate copies, have everyone read it, then have a short meeting--one hour, tops--not to discuss how to do things, but which parts of the design will require a lot of experimentation and fiddling.
- If your dev team doesn't already have someone fluent in Corporate Weaselspeak, then get one.
- Give your translator this sentence: "We will use our magic powers to accomplish this part of the design document." Have him turn it into a five-page monstrosity that lets every stakeholder think these difficult parts are going to be done their way, without really committing your dev team to anything.
- Take the weaselized design doc back to the stakeholders. Your Corporate Weasel's job is to make the stakeholders sign off on it.
- The easy and routine parts of the job get done the way the stakeholders want, assuming their way isn't completely braindamaged. The hard parts of the job will be solved by your development team's magic powers. It's right there in the design document.
- Bring the project to completion. As you're doing the hard part, write This Is How It Really Works documentation for engineers who are coming after you.
- When your project is ready for handoff, make sure to praise the (easy, routine) parts for which you used Marketing's ideas of how the software ought to be written.
- Gloss over the fact that you did the hard part via magic powers. The other stakeholders probably don't care. You're giving them a beautiful bullet point for their end-of-year performance eval. That's what they care about at this point.
- Move on to the next project.
... Is all this weasel office politics? Damn straight. On the other hand, it's weasel office politics meant to shield your development team from unnecessary weasel office politics. As much as we hate weasel office politics, sometimes it's necessary.Mod this guy up +5.
They're all important points. If I had to rank them in order, I'd sort them as follows:
Items 1, 2, and 4 are the most critical, followed by 5 and then 3.
I'd add subitem 4a: During design, don't add features that aren't in the requirements, unless you can show a derived requirement (usually from one what I call the "X-ability" requirments -- scalability, maintainablilty, testability, and reliability). But don't add it because it would be "a cool feature to have".
General Relativity: Space-time tells matter where to go; Matter tells space-time what shape to be.
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)
Ah yes...the infinitely outlined requirements document is my favorite:
...
1.1.1.1.1.1.1.1.1 The system shall not make tacos on demand.
1.1.1.1.1.1.1.1.1.1 The system shall not make tacos on demand with sour cream.
1.1.1.1.1.1.1.1.1.2 The system shall not make tacos on demand with guacomole.
1.1.1.1.1.1.1.1.1.3 The system shall not make tacos on demand with cheddar cheese.
1.1.1.1.1.1.1.1.1.3.1 The system shall not make tacos on demand with sharp cheddar cheese.
1.1.1.1.1.1.1.1.1.3.2 The system shall not make tacos on demand with mild cheddar cheese.
1.1.1.1.1.1.1.2 The system shall not make CHICKEN tacos on demand.
...
this could get messy.
I only mod up parents of "mod parent up" posts...
This meets your requirement; the program didn't "dump". *grin* Hopefully that illustrates the dangers of most "not" requirements.
The best way to write the requirement you're looking for in this instance is something like:
"Ignore alpha values where a numeric is expected."
Or, "If an alpha is given where a numeric was expected, ignore all following input up to [some delimeter].
Or, perhaps, "If an alpha value is given when a numeric is expected, display an error and get the input again." The general idea is you want to define the requirement and the bounds of operation; "not" requirements are unbounded.
I will grant, however, that sometimes you want a "not" requirement; this discussion has more details on 'not requirements' and rjh points out that sometimes folks use not requirements to prohibit things but purposefully allow anything else; in my opinion this is very dangerous and should only be used very rarely.
"There are a dozen opinions on a matter until you know the truth. Then there is only one." - CS Lewis (paraprhase)
The five steps enumerated here are, sadly, rather untenable. In particular, points one and two make a fundamental assumption that I believe is invalid - get your requirements first. If we have learned nothing in the past 40 years of software, and especially in the last decade, it's that we will never have "the requirements." We will have subsets, or views of the requirements, true. The fact, however, is that requirements change during the life of the product development.
Skipping to point four for a moment: I would argue that the requirements should be expressed in the form of tests - functional, unit, or otherwise, and that these tests be executable. The design MUST therefore meet the requirements. This then means that point number three may or may not apply.
I agree that code is not design. Design is abstract, and code is not. And pure-code-no-design folks go overboard in my view, but if you can't have complete requirements (and you can't) then you certainly should document that which is not obvious from a structural breakdown of the code itself. Particularly, documenting risky or unusual features of the code, such as tortured relationships and their semanitcs. To me that is the limit. Document what is not obvious, do not document what is structurally implicit, or otherwise explicit. Documentation covers risk, and risk mitigation points (ie. person hours) are best spent making better software, except when documenting something that, if left unsaid, might lead other developers to an incorrect assumption or conclusion.
As to point number five, your experience may vary. In my experience, it's quite the reverse. But in the example I'm thinking about, we didn't have each individual designing - the whole team designed together, and the whole team coded and tested, and never alone. Also, design changes, or any changes to assumptions (or APIs, or etc.) were well published throughout the team, so that there was ongoing restatement of context. If anyone thought that something was an odd or interesting design feature/artifact, they mentioned it, and the author clarified it and documented it. I don't think having individuals altering design outside of a process of consultation is wise, and I think this "cowboy" flavour of agile developent is abortive and a throwback to no-process development. However, small teams that are engaged collectively produce, in my experience, excellent design. You then need to capture what is not obvious, or somewhat obfuscated, and especially capture assumptions.
Where ThosLives and I would agree, however, I think, is that you need to trace design aspects to requirements. You may not have final requirements, but you always have some, and you shoulnt' make design decisions without a requirement to trace to. In this sense, you absolutely must have tracability from requirement to design to implementation to proof (test). And if requirement can be expressed as a test (not all requirements can), then that is, in my view, the best way.
i - This sig provided by
When I use the blueprints for an automobile to build the automobile, I get something different than the blueprints. I cannot use the blueprints to emulate the functionality of the vehicle. The blueprints are instructions to build the vehicle.
In software, the design is the thing which tells me how to write the code (have you ever tried to read code and find out what the function is supposed to do? generally you can only know what it does, not what it's supposed to do. Sometimes you get lucky and the design is written in the comments, but that's rare; generally comments just say "we watch out for overflow here" or something like "use pointer rather than array lookup to avoud some tricky thing" - comments are usually descriptive of what is going on, not why). If I have a good design I can write it in any language and meet the same requirements. That's a good litmus test for software: if it depends on a language, it's not a pure design. If you have to figure out what's going on to translate into another language, you're in implementation rather than design.
I will grant, however, that there are some difficult situations when you have a requirement "you shall use language X for this project", or "we decided to use language X to meet these requirements" - what happens if that requirement changes halfway through and your "design" was language specific? You're hosed. Good designs are language transparent.
Remember, the goal isn't to produce an application, the goal is to meet the requirements. The design tells you how you are going to meet the requirements ("have a text grid input box" and, at the next level, "have a function that draws a text grid input box") and the code fulfills the design ("textgrid.draw()"). (Note that some design decisions become requirements for a lower level, such as function calls, interfaces, etc.). Code should only be implementation.
"There are a dozen opinions on a matter until you know the truth. Then there is only one." - CS Lewis (paraprhase)