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."
As opposed to some napkin smudged with barbeque wings...
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.
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.
why? is the problem radioactive? Some sort of alien compound that causes forgetfulness? Sounds potentially preferable to some of the projects I've worked on.
Starsucks
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.
Who needs documentation? Just wade in with something like Scrum. Most documentation is out of date anyway (about a month after you're coding, it's useless).
Any sufficiently advanced technology is insufficiently documented.
This story has no posts, just when I tought it would be nice to read from others how they think about design problems.
All I can suggest is: keep a strict separation between features and implementation.
do some use cases that describe how the most important part (the user) will handle the program.
And think ahead, your designs will change while building/deploying. How are you going to accomodate that?
This space is intentionally staring blankly at you
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
Overly rigid structure and formatting are not helpful. Often times I think programmers are so used to writing for compilers that they forget that humans are much better parsers.
Design documents should be easilly written and easilly updated. I prefer a text editor to something where I can have 'really nice' formatting. Its just easier and quicker, and that leads to the documents being more likely to be kept up to date.
If the docs aren't up to date, no matter how well written or well designed they are, they are misleading and unhelpful.
Troll Like a Champion Today
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.
A good design document often duplicates the actual programming process. It starts at a high level (What are we trying to do? How do we do it?) and drills down to the level of what each function (or class method) should do. It should define acceptable inputs and outputs, both overall and for each method. It should also define the unacceptable ones. You should be able to generate the unit tests from it as well as the actual program.
It should leave room for changes if you find out that using methodology Bar to implement Foo doesn't work.
The Final Document should be based on a reading of the code, and any differences between that and the pre-code spec should be documented as to their cause.
Best Slashdot Co
The biggest problem I've had with design documents is that they aren't updated.
When first written, they are good and complete.
As the project moves along and the design changes, the design documents aren't updated. If you are lucky, new features will be covered in errata documents, but old features that were found to be not feasable remain in the document, without any indication of why they were removed from the project.
Knowledge is how to play a game, intelligence is how to win, wisdom is knowing what game to play.
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.
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.
If you can already identify gaps in previous design documents, then you are already qualified to write the next design document.
Apart from that, talk to some other experienced people in your organization and get their take on previous projects failures and delays. Then, see if there is any way to preemptively incorporate measures into the design document to improve your projects chances for success.
[Although, a lot of project success really boils down to getting the right people on the team.]
"Provided by the management for your protection."
If you're really serious about having useful design docs, the only way to do it is to have a dedicated staff whose job it is to keep it current, accurate and useful. Coders are rarely good writers, and even if they are, it's almost impossible to get them to keep docs in sync.
Sometimes it's best to just let stupid people be stupid.
. . . 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.
Write them before you write the new features, to test for the new features.
This will save you eons when you are actually coding. Way too many testers are still wasting their time with manually going through the ssame maotion again and again to make sure it all works as expected.
This space is intentionally staring blankly at you
If your product has a UI, then the design document should start by describing the UI and how all the features work.
If you don't have a UI, then start from the configuration file or command line switches, and do the same thing.
Then you're done. If you can't configure a feature, or can't trigger it from the UI, then it shouldn't exist...unless there are other interaction points.
If you have a network app, document the wire protocol, range of input values, and expected behaviors (of your app and its clients) and outputs.
If it's a distributed system, figure out the different states and document them.
It's actually a pretty simple, though tedious, process. Starting from the UI is a great place, because it shows you instantly how complicated your app is. If it's too complicated, this type of document will show that pretty quickly.
Existence.
At least for most of the projects I've worked on.
Don't document every function and class. That's useless; let Doxygen or Javadoc do that.
Instead, document why you chose PostgreSQL over [foo]. Why you chose to roll your own templating system. Why you fork off jobs in a separate process rather than doing them in one process. Why you wrote this particular thingy as a C extension.
Documenting that stuff will be helpful to folks down the road when requirements/environments/whatever changes and they wonder why things were done this way in the first place.
The Army reading list
Has anybody tried using a wiki for the design documents? Might help keep the documents correct and up-to-date.
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.
I've had excellent success with model-driven development.
The basic process is : create a model that encapsulates the three bigs:
1) Analysis (i.e. requirements, actors, and use cases)
2) Components (object models, system models)
3) Interactions (interfaces and sequencing)
Once your model contains a good description of these three domains, expressing a design document from the model is straightfoward (indeed, many of good modellers will provide excellent document generators). XDE works fine, but my particular favorite is Enterprise Architect
The beauty of treating the design document as an expression of the model is that by changing the model, you change the document.
In a situation where you're doing large scale code-generation from the model, you're living high on the hog - one repository for your solution information, and any number of expressions of that information into the formats you need (requirements docs, design artifacts, codebase, etc...). By actually including the analysis elements of the solution (the requirements, particularly), you can link those requirements to system components that fulfill the requirements. As the requirements change (and, of course, they will), you can evaluate the impact of those changes quickly by tracing the associations.
Decent article on MDD
The most importnat part of a design document is to document what is NOT going to be implemented.
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.
I think that most requirements gathering activities don't involve the right people. Most importantly, they should involve the developer. I have seen requirements sessions involving only the business analyst, an IT lead, and the project manager. They leave out the developer! Usually it is done because the developer is busy with other things.
If you leave the developer/programmer out of the requirements work, they never get the opportunity to understand the requirements and ask questions as the requirments are formed. If you do these two things, you will get much better designs.
www.mikesmind.com - www.daddyworkathome.com - www.freetofarm.org - www.tenfoottable.com
Having someone that can speak and write English do it will go a long way. My current project is working from a design generated by an Indian guy that has no clue what half the words in the language mean. I resent having to rely on half-assed work when I'm not in a position to advise on the design. It's not hard to run the grammar checker.
How does the classic quote go? If it was hard to write it should be hard to understand.
Video game design documents are tricky beasts.
If the design document is underweight, it was good enough to trick the bean counters into giving up the first check. But you really can't use it to build test cases out of it since the developer can add or subtract whatever they want.
If the design document is overweight, you can build test cases with a fair degree of accuracy over the life of the project. The problem is that some developers will bristle at being held accountable for every detail promised and don't like their milestone checks being held up until they deliver the goods.
The ideal design document that lays out what to expect without too much overwhelming detail and the developer delivering to full spec on time probably doesn't exist. At least, not in the video game industry.
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.
Good design documents show intent, but it is the code itself that determine the process. It is like a factory. One has draft and official procedures, but it is the marked up copies on the floor that indicate what is actually going on.
Amazingly, I find this somewhat harder to do in OO languages. The flow is often not as clear due to polymorphism and the like. Makes coding easier, but sometime reading harder. I guess it is just a matter of manners.
"She's a scientist and a lesbian. She's not going to let it slide." Orphan Black
A good place to look is "Software Requirements--Revision" by Alan Davis (1993). I don't agree with everything Davis has to say, but the book is full of good ideas and potential "gotchas" to watch out for. Another good reference is DO-178B, the guidelines used for the development and testing of safety-critical software in commercial aerospace applications. It is available from the RTCA for about $50.
If you're doing an OO project, then you might want to look at Booch's book: "Object Oriented Analysis and Design" and the UML 2.0 specification .
But, most importantly, you MUST have some kind of design documentation (requirements, at a minimum) and that documentation needs to be flexible enough to accomodate changes without causing everything else to grind to a halt while the revisions happen. Expecting to get good software with inadequate formal documentation, minimal planning and insufficient requirements is why 70% of all commercial software projects end in failure (documented and published statistic).
Anyone who says you can do good software by shooting from the hip is nuts. And they don't work for me.
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.
Read Wieger's Software Requirements from Microsoft. It is a very good book to work on. Mainly, our process is:
At least that is what we try to do. Half the time, it is 'You bought what?'
In God we trust, all others require data.
Painless Functional Specifications--not precisely what you were looking for, but pretty close, I think.
I solve all these problems by using the Business Architecture Method from Business Architects The site is new - online examples are coming later today (Monday).
Yes, I'm biased... I work for them.
Here's a cynical view of a system lifecycle
1) A company has a business process that isn't working well because it is understaffed by poorly trained and unmotivated personnel
2) The company decides to automate the business process to make it "more efficient". In the project charter, they justify the project by promising further staff cuts.
3) A project team is formed, and the IT department interviews the poorly trained unmotivated users to gather "system requirements". Which end up covering only a small fraction of the actual business process because the users don't care.
4) The IT department realizes the project is hopeless, and uses lack of resources as an excuse to bring in "consultants".
5) The consultants poor concrete on the system requiremnts to avoid "scope creep", ensuring that the resulting system will be functionally useless.
6) The consultants carefully build a system that meets a minimal interpretation of the sparse requirements.
7) In testing it becomes obvious that the system meets the paper requirements, but is functionally useless to the actual users.
8) The IT department offers the consultants follow on work in return for helping IT blame the users. The users get a staff cut.
9) The system is declared a victory, and bonuses go to the executives who weren't involved.
10) The consultant is hired to fix the system, now called "Phase Two"
"Sic Semper Path of Least Resistance"
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
Exactly. I used to work at a company that had a 50+ page document that was supposed to be used as a template for design documents - a sort of meta-design document, I suppose. Problem was that things rarely fit into their preconceived ideas. It definately led to unreadable documents. The other problem was that the procedure to change the design document was so draconian that everyone was hesitant to change anything even though it would become clear that things needed to be changed when the real world crept in. (BTW: this company allowed absolutely no prototyping prior to finishing the almighty design document - for those of us who like to prototype, it was frustrating)
I'm thinking that wikis are the best way to both communicate and develop a 'design document'. The design document should be flexible and wikis fit the bill. The design document should show the history of thinking about the design and again, Wiki's fit the bill quite nicely as you can look back and see the discussions that took place that led up to various decisions.
Reeves' article really is classic, and hugely valid even today. However, one of his most important points is left dangling.
The software design is not complete until it has been coded and tested.
100% true. The problem is, designers in traditional or semi-traditional development teams usually get only the most rudimentary feedback from test, usually just along the lines of "This doesn't work very well". In some places I've worked in (I'm freeelance), designers pretty much sat in their ivory towers almost without accountability for their designs. XP is different since the designer is more often than not the programmer and tester too, but most dev teams are still structured along traditional lines.
What Reeves needed to stress but didn't was traceability, from each element of design through to the results returned from test. Those elements of design which are too abstract to have actual live machine-generated tests need to have a scoreboard assigned to them, on which the testers can ++ or -- design hits and design misses.
And this very issue of traceability is the key to TFA's question as well, because all documentation except for overviews should be viewed as testable in the same way as any design feature. In particular, modules and smaller components all need to carry their own descriptions, and the accuracy of those descriptions needs to be subject to testing and QA signoff after each change.
It's not a simple area, but where there is a will there is always a way. And many designers do have the will to make their designs stand up to the rigours of testing and quality assurance.
"The question of whether machines can think is no more interesting than [] whether submarines can swim" - Dijkstra
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.
(ducks)
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.
Two things I find that are missing from many documents that I have to work with, are traceability, and references.
References are great (especially if you have a hyperlink) for any number of reasons...
As for traceability, I *loathe* documents like this:
Design document version 1.1
This document describes the differences between version 1.0 and 1.1
And then, version 1.0 is not included as an appendix, and it doesn't tell you where to find it.
As for sticking the 'differences' into a document, and calling it a design, I loathe that too. &*(@# lazy turds!
Start a Wiki from the get-go of the project and keep your notes. Over time, as the implementation changes, it'll be easier to keep the information (as your own reference) up to date as things proceed. Once you consider things usable, you can start forming official documentation using your Wiki as a guide.
As another said, "All I can suggest is: keep a strict separation between features and implementation. do some use cases that describe how the most important part (the user) will handle the program."
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.
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.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)
The Fundamentals: Interfaces and Constraints and that's about it.
The bare minimum is often the best. So, include precise definitions of the interfaces that the code has to meet, including any tests that it must pass and the constraints within which it must fit.
If it is firmware, then hardware interface specs must be included as well as whatever interface the firmware must provide for other system code. Add to this performance constraints or requirements and you are done. Leave implementation for later.
If it is module constructed in isolation, again the interfaces must be clearly defined and performance requirements declared.
Constraints define the resources allocated to the code. Performance requirements are a sort of constraint on time and hardware allowed. There are also other constraints that are usually implied but not stated like how long the engineer has to implement, test, debug, etc. This is effectively a cost constraint.
Implementation can also be documented, but is not fundamentally a part of a design spec. Sometimes code comments can be enough. Sometimes a few notes about competing implementation ideas and why one was chosen over the others can be helpful, but not as part of a design spec.
Keep It Simple Stupid - define what the module(s) must do, what tests it(they) must pass and that is it. If you do this right, then the implementation can speak for itself.
Good judgement comes from experience, and experience comes from bad judgement.
- W. Wriston, former Citibank CEO
It's simple, make sure that each requirement that is stated in your design document meets the testablility test. If you can't think of a simple way to test the requirement, than it isn't properly defined.
Along with this simple idea, the person who is specifying the system has to be willing to put in the time to make sure all requirements are testable. You also have to have a good programming manager, one who will make sure each new requirement is checked for testability and that all changes are checked to make sure they don't mess things up.
With this combination of factors, I was able to reduce the number of errors discovered after release in one system from over 400 (taking 4 months to fix) to 4, which took three days to fix.
Make note of the tests you envisage for each requirement. Ideally, this should be done by a very sharp-eyed QA Analyst.
Finally, build code reviews into your schedule. That way you have a good chance of meeting your deadlines. The code reviews not only find many bugs, they are also good places for mentoring members of the programming team who have less expertise.
Hopefully, some of this is useful to you.
-All that is gold does not glitter - Tolkien
www.ra
It must compile and run correctly.
First trick: Empathy. You have to understand your target audience and write to inform them and fulfill their needs. Don't try to appease every audience with the same document--engineers need to see a much different document than marketing.
Second trick: Brevity. Put NOTHING in there unless it communicates the design and is required by the target audience. Get rid of Cut & Paste boilerplate just as you would in your code.
I guess finally I'd have to say --be complete. If you find yourself saying "We'll work out the details of that later", it's going to be one of the more difficult parts of your project.
The problem is that these standards are difficult to quantify, so the most important point would be Hire a good architect. Look at design docs they have written and see how many questions you might have if you were implementing that project. Let them train the rest of your staff.
The difference between a typical programmer and a good architect is about the same difference as that between a house painter and a classic artist. Even if a group of house painters could paint the Sistine Chapel, they would have to have some pretty good instructions to follow--and they would be completely incapable of making those instructions themselves.
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
Reading through some of the comments it seems that other engineers and those that havn't progressed to that level, don't indicate who should be reading the design documents. The audience for design documents are your collegues. Before you begin your document you should start by reading theirs. A good PHB should force you to.
A good design document should describe what you want to build, what you need to change in the existing system and what your dependancies are to name a few. It should spell out how you want to order you classes (UML!), most importantly how you will use the global classes (like an user class).
Therefore, if any one of your colleagues can read your document and think one of the following thoughts your document was a success:
"Oh Joe wants to use the user class like this, I guess I won't change it to stop that from happening"
"I don't think Joe knows that I'm building a Foo class since he thinks he's going to build one, I'll email him and we'll decide who's going to do it"
"I see that Joe has this great system designed, but he seems to be forgetting the requirement that we have to let the end-users configure it through the app and he's only using property files. I'll email him and make sure he didn't forget that."
"Uh... what the hell is Joe thinking, there's an existing class that does exactly what he wants to do, why did he waste his time writing this document?"
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
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
All of this talk seems to assume that there's at least some excess manpower to be thrown at the problem, that the customer knows what they need at the time of specification, etc. It doesn't allow the softare to become what it was meant to be, but only what the potentially narrow mind of one designer allows for early in the process.
I work in control systems. We have in-house motion control software that we use to do weird jobs. This software is not as featureful or complete as the packaged solutions, but it is cheap to deploy, and designed to be expandable and flexible. A project might entail anywhere from a few hundred to a few thousand lines of custom code that sits on top of the 30-40klocs of core code.
When a customer requests a CNC retrofit of an old or weird machine, they seldom have any idea how the machinist on the floor actually uses the equipment. They see the problem as a basic one--the machine takes too long at X or the machine lacks capability Y. The machinist is not really a programmer and isn't mentally prepared to make the leap to writing a specification.
The solution to the problem was for me (a programmer) to go into work with the machinist for a few days when the software was about half done and help him make the parts he needed to. Even though the software was incomplete, I could at least step around any immediate problem by throwing a little bit of prototype code at the problem and get the operator's feedback regarding the process as a whole and how it could be changed to make his life easier.
I guess the point I'm making isn't fully formed, but all this talk about design processes seems to be missing the essence of that project, which was only possible by allowing the sole user of the software and the programmer to spend time collaborating. For much of the coding, I brought my workstation to the factory floor and worked right there. It made testing much easier and let me ask the operator questions whenever an issue arose that hadn't been forseen by my boss or his when they planned out this task and designed the system. I would, of course, run major changes by my boss first, but he pretty much trusted what the operator and I were figuring out.
We've been providing custom software to this company for several years. It's pretty much run without issues and has saved them huge amounts of money, essentially by optimizing a handful of machines in there shop. The project would never have gotten off of the ground if we'd been caught up in these sorts of formal processes. We don't have the manpower, or the timeframe.
Think about that. If the the software you are creating isn't altering the business methods, the usage patterns, the very opportunities available, why are you bothering?
New software should be disruptive. It should enable things that were never present before. It should create opportunities that simply weren't even on the horizon before.
If it doesn't, then why bother? Make do with the old version. Patch it, kludge it. Software is incredibly expensive to write, so unless it is really disruptive, don't do it.
So your system is worth creating, it is disruptive. THEN IT'S PRESENCE WILL CHANGE THE REQUIREMENTS.
Thus the requirements gathering, design coding, testing, deployment must occur in a tight a loop as possible. The system must be flexible as possible to keep pace with those changing requirements.
This is what extreme programming is about. It is "Extremely Conservative Programming". It is performing the conservative best practices that traditionally, give us quality systems, at a sufficiently high rate to cope with the disruption our software produces.
You mention the designer is the coder is the tester in XP. Wrong.
The coder / customer team are the requirements gathering, priority setting team. The tester is the designer, forcing the designer to design testable systems.
The coder is the implementor constrained by superbly tight design / spec (the test), earning the greatest value to the customer soonest.
The coder then changes hats and becomes the refactorer, who can in the light and hindsight of the evolving system create a superbly designed and crafted system. Why? Because the system was designed to be testable, it is deeply tested so refactoring is safe. It won't unwittingly break the system. And being superbly designed, it is flexible, ready to earn the next greatest chunk of value for the customer.
And having come out of implementation with a higher level of testing than most traditional systems, it is ready for deployment to the customer. It can start to disrupt his business, start changing the way he does things, start changing requirements and priorities.
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.)
Yes. Tetris and MS Office have the same target complexity, to within fifty percent. Also, generalizations are helpful.
StoneCypher is Full of BS
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)