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.
The person writing the document should have enough software/hardware resources. So many engineering specs are written too early in the phase when there is nothing tangible. It just becomes a fairy tale document.
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
Design documents are a waste of time. I have never seen one that is current, or even comes close to explaining the system accurately enough to be useful. The best solution is to write code that is easy to understand and go from there. Maybe create a high level diagram of the system, but let the code be the language in which the design is written. Do you really think the design document comes first? It never does. It is always done after the code is completed, and only because management has no clue and thinks documenting the system will make is easier to hire new developers. I'd honestly suggest looking at the design side of XP. I have used that a lot recently and have seen hug improvements in efficiency and code quality.
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."
I would still say that code is the best design. (these are not my word. I had read is somewhere and I forgot. Sorry about that, else I could have linked it). The article said that code is the best design document and shoudl be considered so. The actual 'construction' phase happen when the code is compiled by the compiler.
fuvoo: watch something
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.
But sadly we are all part of the vicious cycle
Top 10 Reasons To Procrastinate
10.
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
Go here for teh [sic] funny.
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.
>> if all else fails, where's a good place to find all this stuff out?
fastForward (till the end of the project)
Look (comments)
If (no comments){
setdesign(null)
worry(no)
}
else{
setdesign(comment)
}
comeBack(present)
getDesign()
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
.. and if there is, I've yet to see it. :-)
;)
Short answer:
Some UML (Use Case + Activity + Class) documents and a technical textual description of the task.
You can of course add more, but in 99% of the time, the programmers will either ignore or overlook it.
Long answer:
We (small software business) are working on making our inhouse design documents more standard.
One of the things we ran into was also the "What should we assume to be basic knowledge for a design document" question and after having spent some time, we came to the conclusion that design documents had to be so basic that you can replace a programmer in almost any state of the project.
Based on above we made an estimate on how long it'd take to make the proper documentation, showed it to the manager, got a swift "fsck no!" reply and went back to the old system of poor documentation, but high productivity (and many bugs
Personally I try to aim for the "three developers" goal. If three non-involved developers can understand it and come to the same conclusion as me, then it's all good.
-- Thou hast strayed far from the path of the Avatar.
My preference is to get a list of features from the customer in the form of User Stories, and turn those directly into Acceptance Tests.
Tests tell you what to do, and when to stop.
I also put a rough estimate on the various user stories, and then let my client prioritize the stories so the work I do first is what they want most.
In many cases, clients don't know what they want until you don't give it to them. The best approach I've found for those cases is to whip up a tiny prototype to show to the clients and ask them what they like and don't like about that prototype.
Clients know what they want, but they rarely understand what's hard and what's easy when it comes to software.
So, I think design documents are best as a bunch of 3x5 cards holding user stories, along with matching acceptance tests.
Shae Erisson - ScannedInAvian.com
As I have learned from classes, following IEEE standards to the T!!!!! Go 830-9993........... What? You mean there's more to writing a good document then following the standards? Impossible.......
In undeveloped countries, the consumer controls the market. In capitalist America, the market controls you.
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.
>>If I have to choose between a 50-page design document and three pages of clear diagrams, I'd pick the pictures.
Bingo!! No stories, only porn pictures.
A Good Product Manager
This person should follow the development of a product from beginning to end, and document as well as be responsible for the production of the Design Requirements.
The Product Manager should work in the business/marketing side of the company, as ultimately the customer will determine the success of the product, however they should have a strong enough background in the technologies that they aren't some caricature from a Dilbert cartoon. It isn't necessary to define individual segments of code since the basic technologies may change by the time the project moves to design and later phases - but the end results of the implementation of the elements of the product should be documented, the developers can then always know what their product should be capable of. Of course everybody who does work should be documenting their work and ideally to document specs laid out by the Product Manager to ensure consistency with all the product materials.
The rock, the vulture, and the chain
I have worked for organizations that uses Lotus Notes extensively.
[diety] save me from documentation that consists of links upon links upon links. I certainly find this disconcerting, and I imagine I'm not the only one in that execution based on these documents often seems disjointed with significant factors going lost in the process.
Whatever you put together, try to ensure it's not blown into thousands of pieces. Documentation requires some effort; updating should be more than just glomming on a paragraph at some document boundary or via yet another link to an independent context (independent document). The payoff is when you can actually get an overview of what you (and OTHER teammates) are doing, in a reasonable amount of time and with a reasonable amount of effort.
It also protects your organization from the proverbial "run over by a bus" (as in, the only one who knew this just was...).
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
In my experience, I'll be honest and tell you that design documents are a pile of crap. They're usually written from a limited point of view with the assumption that you understand all the nuances of the business. Most of the time, that is not case.
You're a lot better off talking to the key people involved in either the business process or decision making. If you're working for a smaller company, this is relatively easy to do; however, if it's a larger company, I would think it's more difficult (ie less access to the managers). But find out how the process works and what people are looking for in a system.
The key to obtaining the right information is to ask the right questions. Don't approach with, "Hey, I'm designing a new system, what are your needs?", but rather approach with questions regarding problems with the current system. Then, when you get a feel for everything, you can design a system that will fit the right needs.
IGB: More fun than eating oatmeal!
Design is the "how", a tactical plan that requires the "why", or the strategy. What functionality is required? The strategy is often not in place.
Requirements documentation is the "why" and the strategy driving the software development. This should be done before the design and is almost always neglected. This becomes more important with either feature creep or software maintenance. The "why" will always help to keep focus on the important factors in mind.
If requirements change, there is often a value attached to those changes. As a result, the justification for increases in development are often understood and accepted. In the outsourcing development world, it is also the basis for a contract to show that the program meets the needs of the customer.
Spoken like an experienced Extreme Programmer.
The net will not be what we demand, but what we make it. Build it well.
There is lots to say about design documents but one thing I always find to be lacking is how up to date the documents are. Mostly they are written for some sort of release and then left untouched again until the next one. That's bad. Enforce that any change to the software in terms of features and requirements has to be documented as part of the implementation task. No bug or change requests gets closed without the documentation being done and being up to date... Hard to achieve but once you documentation is concise AND up to date you will be a great step closer...
The most importnat part of a design document is to document what is NOT going to be implemented.
Yep. Reference the requirements document from the design document, showing how aspects of the design address each particular requirement.
You may also find it useful to split the design document into a hierarchy of many; one or more high-level documents for module-level descriptions, each having one or more low-level design documents for stuff like unusual algorithms or other non-obvious aspects of the design of a particular module.
A good design document, like any technical document, should be well written. All too often, something that could take a sentence to write is expanded into multiple paragraphs or even pages, because the writer likes to feel important. Keep it relevant, and keep it simple.
Also, despite what they tell you in academic paper-writing classes, it's *all right* to write in everyday language. A statement such as "The user moves pointing device A over the activity area of the button in question, intending to activate Process Retroincabulator, and presses the button of activation." can easily be replaced by "Click button A."
Less is more. Each unhelpful word the engineer has to read in a hopelessly long design document brings them one step closer to "Screw it, I'll do it my way and get yelled at later." Reread and revise, removing as much unnecessary verbage as necessary.
-- I prefer the term "karma escort."
The basic idea behind writing anything right is to know your audience. You've used these documents before -- write out a list of all the information you, as a user of these documents, need to get out of them to do the work properly. The format, etc., should support the answering of these questions -- don't decide on a format/structure and then shoehorn the information into it.
<sig>Guvf vf abg n frperg zrffntr
The best thing you can do is compose an outline or draft and show it to as many people as possible. Get feedback, criticism, and suggestions, and update the outline. Then get feedback again. The more eyes, the fewer mistakes.
No matter what the official titles may be, the real design document is the test plan.
This is because if the product should accepted if and only if it satisfies the test plan. A good test plan will thoroughly exercise the conditions that the product will encounter, and specify the expected response. Once you know those things, generating a traditional design document is trivial (plus or minus nontrivial graphic design).
Because PHBs expect something called a Design Document, I suggest you build a database of Product Condition/Responses (e.g. "Condition: Push Red Button; Response: Sound Klaxon") which you can sort one way to produce a design document and another way to produce a test plan. This is not intended to be cynical; design documents may need to be organized differently than test plans.
--- Attorneys Assisting Citizen-Soldiers & Families -
I've taken a few software engineering courses, there are two main documents of a design spec. I'm not sure from your post whether you're lumping them into one or not, but they are Requirements Definition and Requirements Specification. Look up ANSI/IEEE Standard 830 for the full blown layout of these things. You can tailor them to suit your needs (not all the guidelines need to be followed)
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 have never worked for a large software company. How is a large design effort that goes into something like Windows or Oracle documented and maintained. I am sure these companies would separate people from processes and maintain the independence.
... 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.
Every design involves choices and tradeoffs.
Each of these requires a decision.
In order to intelligently maintain and extend
the project, the owners need to know why each
decision was made: what were the design goals,
what were the available alternatives,
what were the constraints, and what might be
done under different alternatives or constraints.
That is, explain why the design is the way it is.
"This algorithm has n-squared behavior, but
was easy to implement and test. N-squared
behavior is tolerable for a small number
of fazzbarns, and we are fairly certain that
no more than a few fazzbarns need ever be supported.
If the glup module is ever scaled up to produce
more fazzbarns, this will be a bottleneck, and
the well-known but much more involved RTTD
(Right Thing To Do) approach, with n*log(n) behavior,
would be much better."
He's no fun; he fell right over.
Wait a minute. Didn't I say that on the other side of the record? I'd better check
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
I like to describe why I did things in a particular way. Much of what ends up in a design document describes what the system does (I can run the app to see that), or how it does it (that's what the code is there for and I guarantee that the code is more recent than the design document).
What always gets me is when I show up and ask "Why didn't you use XXXX?" No one knows. Often there is a really good reason that I find out after weeks of unsuccessfully attempting to implement XXXX.
90% of everything is crap. Also, crap is relative.
In 20+ years of programming, admittedly all in groups of 15 or fewer programmers, I have yet to see a good design document. Most design documents are obsolete as soon as a significant amount of code has been written.
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.
However, most of the time, the code rarely stays true to the design. Things come up and the code has to keep adapting and changing. By the time the software is released, the design document reflects the original intent and not really the actual design of the system.
As a result, it less useful and may even be misleading to someone new.
If we do the opposite and let developers write design docs after coding, there is often very little interest in work that is already done, so the docs turn out to be very sparse.
IMHO, the best design documents are closely tied to the code itself and constantly gets reviewed as a part of the code reviews as well. That is the only way to make sure relevant information is documented and that the document stays fresh.
All your favorite sites in one place!
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.
Every document should focus on its audience, which in the case of a design document changes over time. Its goal should be to get the reader up to speed on the target program or system, with as little self-aggrandizing fluff as possible. Keep it simple, and work from the top/outside to the bottom/inside.
It should always give an overview of the program, telling what each chunk does. It should also tell how the program does what it does in terms of the chunks of the program, but not the details of how each chunk should do what it does. It should tell how the chunks relate to accompish the task.
At first, the design document should specify the boundaries of each chunk of the program or system being developed, along with the data to be exchanged at the borders.
As time goes on, and the work progresses, the design document should be changed to reflect the current status, as if there were no work completed. The goal is to zero in on the completed program, not to have it expand out of control, so you have to watch that.
When handled properly, the finished program and the finished design document make a better finished product. When handled incorrectly, you have either unimplemented or undocumented features, two classes of bugs that are particularly annoying for the end user.
sigs, as if you care.
There is no "best method". There are however, some good cliches to follow:
1. Less is more: The less detail you go into the more likely it will be relevant.
2. A picture is worth a thousand words: simple high level diagrams are good.
3. If you have nothing to say, say nothing at all: write documentation because it is needed, not because you feel you should.
4. Don't be a copycat: If the code documents what needs to be said, don't duplicate the code in your documentation.
5. Those who can not remember the past are condemned to repeat it: Team knowledge is your greatest resource. A "living history" will give you a better understanding of a piece of software than a document ever can.
Where I am working we are experimenting with using a Wiki for writing and maintaining documentation. It might be worth your looking into.
Also, using something like javadoc for documenting you classes and class files is probably better than writing a separate document.
I've found most useful three things:
Class Diagram
Use Case Scenarios
Flow Chart
The class diagram I think is the single most useful doc for any OO project. It tells exactly what the package/application/whatever can do, and often gives some insight into what the designers were thinking.
Use case scenarious tell you how the designers imagined the program would be used. You can also ask users to write down how they envision their interaction with the program.
A flow chart or state diagram or something similar for the app if needed. The larger the app, the more useful this is.
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.
Design docs are like flowcharts. You write them AFTER the system in implemented. That way, you don't have to explain why the system doesn't fit the documents.
If you aren't part of the solution, there is good money to be made prolonging the problem
I try to keep mine current, revving them after peer reviews, low level designs, test plan reviews and customer discussions. I also try to be as complete as possible, within reason, so that the outcome (i.e., what the product actually does) is predictable. A hard thing to do is maintain traceability between requirements and the resulting software and test plans, and I've not seen good tools to do so (I've seen lots of tools, but they all seem to require too much overhead).
Once I have a solid design doc for a feature that is released and dpeloyed, I turn the doc into an Interface Control Doc or incorporate it into an existing one, which is then kept current with subsequent changes.
None of this is perfect but it seems to work and is fairly low-overhead if everyone buys into the process.
Mike Borella http://www.borella.net/mike
Things that get FULLY documented become so obtuse, esoteric and bureaucratic that they can never actually work without huge teams of people. Look at CORBA, X.500, iCAL, and government defense contracts.
Things that are over simplified (HTTP,SOAP,SMTP) take off quickly and people are left to their own devices to fill in missing protocol gaps, causing huge future headaches.
The best way to split the difference is to make LOTS of simple design docs that allow for multiple iterations, where no single document becomes a monster (the CORBA spec is currently over 1000 pages).
----- Refactoring is the reason why man does not mistake himself for a god.
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.
Every time I want to check out a game I go straight for the screenshots. A picture says a thousand words and all that. Pictures at the start of the doc are a good way of quickly explaining what it's roughly about.
I think another important thing is to explain why you made certain decisions. Just stating things like facts and leaving out your justification and thought process will make you decisions seem like arbitrary opinions.
Naming characters Azearoth and Kyliandra is not game design. Keep things fuzzy, details later. The concept should work on an abstract level.
The Chair Corp. comic(*00-12)
"...Make that shit up as you go!"
Why can't all fpga/microcontroller manufacturers just release free optimizing compilers???
Documentation is a good place to start and it may give a reasonable overview (sometimes) but I've found the best place to start is with the people that are still on the project that have written what already exists. Use their knowledge and their experience with the specification to first get a feel for how things lie and where they need to go next.
Written docs vary so much in accuracy and detail. It's too easy to read docs and think you know how things work just to find out that's where things started but now they're completely different. Sometimes the docs you have can really mislead you and waste your time. Start with the people, then do a quick once over of the docs, then start reading code. That's the way to get an accurate picure as quickly as possible.
I frequently find that design documents do not have enough of the reasoning behind why a decision was made. Issue Based Information Systems (IBIS) is one way of recording this information and I have seen people use this technique successfully. But what may be of more value is to setup a designated mailing-list/newsgroup/blog/journal for the project that can be accessed (online and searchable) in addition to any formal documentation that is generated.
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 like to see... ....
a) meaningful title
b) Table of contents - even for short documents, any modern word processor is good for this (mark headings as you go along and most can just insert one for you automagically
c) glossary (up front), there will invariably be TLA (three letter acronyms) that arn't obvious to all readers. Just assume that every TLA needs a one liner.
WIFI , WIreless FIdelity - Superset of
d) SHORT Introduction in the narative (i find it makes things more readable "In august 2004, blah blah project was undertaken to blabh blah".
e) function, stored procedurs, whatever correctly names with UML or other data flow diagram approach.
f) high-level data flow diagram.
g) network diagram (however trivial it may seem).
h) Points of failure / or future upgrade path (note specifically not implemented features and why). I've read too many dd's only to discover half the features don't exist.
"If all else fails, where's a good place to find all this stuff out?"
Ask your boss... geez. Next question?
Purpose
Requirements
Definitions
Business Rules
Use Cases
Wire Frames (UI)
All of the terminology within the document is non-technical and basically describes the said business process and the proposed technical solution. In my experience the clients always flip to the wire frames section of the document, since this is the easiest thing for them to understand (pretty pictures!). A wire frame is really just a stencil of a screen created in any modeling tool.
So now you must be thinking why is he mixing design with definition work? I'm sure some would argue that the wire frame need not be in the RA document, since this is really design. However, a client may find it easier if they can walk thru the use case while looking at a screen representation.
Once client sign-off has been obtained that's when we get into the fun design stuff. Depending on the said tasks complexity you can utilize UML to further document the process. Any design documentation will be separate from the RA documentation but it will accompany the RA document when handing off to a developer. To me the single most important design document is the class diagram, and depending on complexity possibly a sequence diagram. I use UML on an as needed bases, you'll never need it all, but pick and choose different pieces as you see fit.
The 5 D's of software development:
Discover (Business Briefs)
Define (RA Document)
Design (UML)
Develop
Deploy
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.
There needs to be a page, either included within or accompanying the design document, which describes the real reason for doing the project. Put it in plain language, rather than padding it with legalese or marketing jumbo.
There will inevitably be gaps in the technical specification, and it will be up to the programmers and project leaders to use their best judgement where the design leaves off. Give them a conceptual roadmap, so they have an idea of what they are really doing. They'll understand what needs to be well-designed and what can possibly be skimped on.
Having such a "Mission Statement" will reduce the risk of spending too much time on details which really aren't significant in the grand scheme of things.
If the project's reason for existence is to artificially inflate monthly sales figures for your suppliers through a system of prepaid consignment, put this in writing. Don't keep your technical people in the dark, even if it's a dirty secret. If you obfuscate and tell them something like, it's about "enhancing channel flexibility," not only will the project take longer, but the final result won't be as bug-free or effective.
Do you really want your engineers wasting their intelligence on trying to figure out what their job is for? They WILL figure it out, over time, at the water cooler. If it's not what you say it is, worker morale (and future projects) will certainly suffer.
Your design document needs to be culturally relevant:
Include a Hindi translation next to the English
Include culturally relevant analogies to help the programmers:
This will help the quality of the code immeasurably
-- What?!?!? I'm not bitter!!!
"Meaningless!, Meaningless!" says the Teacher. "Utterly meaningless!"
Read the Jack Reeves article from C++ Journal. His main message is that software IS design. Code IS design. Convincing your designers that this is the case will be difficult, but the best takeaway from this is that whatever your design is, keep it as close to the code as possible. If blocks of the design document do not naturally copy&paste as comments into your code, something is seriously wrong. Either the "design" is wrong, or your code is wrong. Keep the 2 close together and it should be easy to decide which needs tweaking.
The question is: how many times will a document be consulted in the future vs. how much time, effort and cost do we want to incur to make it perfect? By creating ad hoc documentation via a searchable communication tool (tracking system), you incur no extra cost yet all of the information is there someday if you need it.
The people working on requirements and the design will through a series of meetings argue and debate over the design until a handful of key folks understands it. Usually the implementing team or individual understands it the best. As "discoveries" reveal flaws, that team meets and discusses the changes.
These people don't need the docs. The docs are really for the poor sucker that gets hired a year later - i.e. somebody new to the project. Those poor saps have to get up to speed. However, design docs (if up to date) don't show the whole picture. They just give a snapshot view of how things work. Having the thought process, the decision process, the proof (if you will) of how the project was pieced together with some kind of discussion database is the best tool these people can have. Plus, it eliminates stupid questions. As an original implementer, if somebody askes you a question on how or why you did something, you can refer them to the forum/mail thread/etc (like you remember).
Someone you trust is one of us.
You might want to research the A-7E method for specifying software systems. It's a highly structured documentation method created by the Naval Research Library (I think) for the A-7E aircraft software systems. It can be applied (and modified) to work for any software system. Of course, this is a method for documenting the system specification, but it might work for you... What's the difference between a spec and a design doc again?
For me, the documents that finds the most use are the sequence and the logic flow diagrams. They can both be used by developers and make a great starting point for process flow documentation for end users.
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"
...but there is no one right way to do it. I suppose that's the whole problem. If it were standardized, then people would not have such problems (though the gaps in the docs may still be there).
In any case, some people will tell you that such desgin documentation is absolutely essential and absolutely required, and there are those who think that they are an absolute waste of time. The truth is somewhere in-between. It depends on the projects and the organization that you work for and their adherence to standards and methodologies.
I for one, think that the documentation should be minimal but complete, and no more. Strive for conciseness. Nobody likes to read reams of documentation and then try to figure out what needs to be done. Lots of overhead usually exists in these design documents.
I frankly think design documents should not exceed certain lengths - artificial limits are not useful, but the main point is to break up documentation into smaller chunks and then work on keeping the amount of documentation that one has to read and understand in one go smaller (kind of modular programming, gee).
structure and organization will allow you to create more concise, modular and portable designs and design documents...
I have to say though, this is coming from someone who hates reading documentation of any kind.
Humans are more forgiving than a compiler, but humans don't always exhibit the same behavior given the same command. This, for many, is the primary frustration in writing software documentation.
The truth about Scientology, Xenu, and you: Operation Clambake
I'd check out the ReadySet project, hosted on Tigris: http://readyset.tigris.org/.
ReadySet is a collection of templates in HTML and CSS for project requirements and specification. Even if they're not perfect for your organization, they can serve as a starting point.
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.
Make sure all the requirements for the procedure/class etc are rigidly and unambiguously defined. Implement them as required and develop test cases that test the requirements/bounds/etc. If there are problems with the requirements then validate everything first.
"If you are a dreamer, a wisher, a liar, A hope-er, a pray-er, a magic bean buyer
We have implemented this typoe of procedure in several projects in the sofware company where we work and we have been very pleased with the results.
"There is a terrorist behind every bush"
With test-first development, one can even work in tests with the design docs.
class TestMyUnit Test::Unit::TestCase
def test_feature_foo_with_bar
a = Foo.new
b = Bar.new
assert(a.frob(bar))
assert(File.read('designdocs').grep('Foo connects to Bar'))
end
end
That, along with some statements of purpose for each bit and a commitment to keeping things simple should suffice. Each feature should be mentioned in the design docs, at least. The rest is just work policy on keeping it up to date.
What makes a good design doc is usually a good requiremens spec. If you can get a user to sit with you and describe the system in excruciating detail (at least the parts they know) including all functional and non-functional specs and business rules, the design doc is incredibly easy to put together.
That's not to say that the requirements won't have to be altered once the design doc exposes conflicts or flaws in the requirements but a good user who's willing and able to put in the time and a good Business Analyst (best when it's not the developer but still someone moderately technical) make all the difference in getting scope limited and driving the desgin phase.
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
A (good) design document, from my perspective, helps me understand the actual massive codebase I'm pitted against. It tells me what things the system is trying to do, what are its major pieces, and how they fit together, so that when I look at one particular piece of code, I can understand how it fits into the whole, and thus be that much less overwhelmed by details.
Another way of putting it: I've been asked a lot of times to work on a really complex piece of code, and have had to look at it, almost completely lost in it. Then I go talk to the guy who wrote it (and luckily, most of the founders in my company are still around), he explains what it's trying to do at a very high level, and how it does it, and then, when I go back to it, it suddenly makes a lot of sense. A design doc, in my mind, should aim for exactly that.
I thought RFC's were the poster child for an incomplete requirements document. That's why everybody goes back to the original source code for Network Protocols.
The strength of a design doc really relies on the documents that should come before it. A solid functional spec leads to a solid software requirements spec which allows you to create a solid design doc. It's when the process isn't followed and things are done first and then documented where you get the problems described in the story. I've found managment is more than willing to excuse you from doing part of the process if it means they can have the change done right now.
-Interface definitions
-Key Objects/Data types/Schemas
-Diagram showing where the new software fits in a system
-Diagram showing internal make up of you design
-Definitions of what each internal part of your deisgn does and what it is responsible for
-Explanation (maybe in diagram) of how the design solves some key requirements. handy for testing the design
-Requirements that can't be met by the proposed design (and maybe mitigations)
-A presentation to reviewers, explaining the design verbally, before they try and just review the document (give them a head start).
plenty more......
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)
Sample spec
"Here are some of the things I put in every spec.
A disclaimer. Pure self defense. If you put a paragraph saying something like "This spec is not complete", people won't come into your office to bite your head off. As time goes on, when the spec starts to be complete, you can change it to say "this spec is complete, to the best of my knowledge, but if I forgot something, please tell me." Which reminds me, every spec needs:
An author. One author. Some companies think that the spec should be written by a team. If you've ever tried group writing, you know that there is no worse torture. Leave the group writing to the management consulting firms with armies of newly minted Harvard-educated graduates who need to do a ton of busywork so that they can justify their huge fees. Your specs should be owned and written by one person. If you have a big product, split it up into areas and give each area to a different person to spec separately. Other companies think that it's egotistic or not "good teamwork" for a person to "take credit" for a spec by putting their name on it. Nonsense. People should take responsibility and ownership of the things that they specify. If something's wrong with the spec, there should be a designated spec owner, with their name printed right there on the spec, who is responsible for fixing it.
Scenarios. When you're designing a product, you need to have some real live scenarios in mind for how people are going to use it. Otherwise you end up designing a product that doesn't correspond to any real-world usage (like the Cue?Cat). Pick your product's audiences and imagine a fictitious, totally imaginary but totally stereotypical user from each audience who uses the product in a totally typical way. Chapter 9 of my UI design book (available online for free) talks about creating fictional users and scenarios. This is where you put them. The more vivid and realistic the scenario, the better a job you will do designing a product for your real or imagined users, which is why I tend to put in lots of made-up details.
Nongoals. When you're building a product with a team, everybody tends to have their favorite, real or imagined pet features that they just can't live without. If you do them all, it will take infinite time and cost too much money. You have to start culling features right away, and the best way to do this is with a "nongoals" section of the spec. Things we are just not going to do. A nongoal might be a feature you won't have ("no telepathic user interface!") or it might be something more general ("We don't care about performance in this release. The product can be slow, as long as it works. If we have time in version 2, we'll optimize the slow bits.") These nongoals are likely to cause some debate, but it's important to get it out in the open as soon as possible. "Not gonna do it!" as George Sr. puts it.
An Overview. This is like the table of contents for your spec. It might be a simple flowchart, or it might be an extensive architectural discussion. Everybody will read this to get the big picture, then the details will make more sense.
Details, details, details. Finally you go into the details. Most people will skim this until they need to know a particular detail. When you're designing a web-type service, a good way to do this is to give every possible screen a canonical name, and provide a chapter describing each one in utter and mind-numbing detail.
Details are the most important thing in a functional spec. You'll notice in the sample spec how I go into outrageous detail talking about all the error cases for the login page. What if the email address isn't valid? What if the password is wrong? All of these cases correspond to real code that's going to be written, but, more impor
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!
wafer thin...
Onward to the Aether Sphere!
It's a standard and it works.
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.
is one that does not allow editing by the sales staff.
GET FREE APPLE STUFF!
Interesting discussion. Any advice for this situation?
My employer hired an outside software vendor years ago who has provided us with very little end-user or developer documentation. I am new here, and I'm the only person on staff with any technical background or experience. In my opinion, we're being taken for a ride.
Granted, the software generally works, and it provides us with a revenue stream. But for what we're paying, I'd expect it to be spit-shined and polished, well-documented, and easy-to-use. It is none of these things. My guess is that we could have better products, better consulting, and better support for a hell of a lot less money, so "generally working" doesn't cut it.
My fear is that said documentation doesn't even exist. We're not ready to jump ship yet, but I wonder what steps we might need to take in order to jump ship. How do you go about getting a legacy developer to document the years of work they've already produced for you so that hiring another vendor is even an option?
Money.
Far too often "good document" is an oxymoron. But what you need to have documented can vary significantly from project to project. For our distributed systems, the one piece has always been missing is a description of all of the interfaces used. We currently range from RS-232, with or w/o 202T modems, to plain sockets over TCP/IP, SSH tunnels and some DCOM. Throw in LonTalk and RS-485 on the side, and you have a real mess. Without adequate coverage for each, it is very difficult to decide where to connect a new component, or what capabilities each interface has. We also can't explain which ones are deprecated and why, which means we still get sales orders for combinations that no longer, or never did, work.
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
Three things to think about:
(1) As above, shorter is better.
(2) Eschew obfuscation. Simple, clear, active, declarative sentences are best.
(3) Keep the notion in mind that you're creating a contract. You shouldn't develop low-level details, you shouuld state in a very crisp, preferably testable, fashion what you expect from the thing you're designing.
The biggest issue I've had with design doc is maintaining them.
A system design is a living animal, but often, the doc gets written before the initial development starts and isn't modified when changes are made later.
After a few revisions, the design doc can easily be out of date.
I think this often happens because the changes are typically smaller and easier. Therefore a developer won't bother with a process for them (when spend time documenting something that you can do in 1 hr and double the amount of work) and instead just go ahead and make the change. A few months down the road and the system may not even reflect the design doc.
If you can find a way to maintain the doc without it being a hassle for the developers that could help make the doc actually useful.
When you have a question that the documentation does not answer, find the answer and then document it. If each member of the team does this, the documentation will evolve to a useful and current state. If some do not do this, the documentation will not be as good, but unless you are the person creating and enforcing policies, you simply have to accept it. I do not think there is a set "answer" to the question, "What documentation is good?" Like a Slasdot post review, many people have a hand in "documenting"; each person offers their perspective. If you have enough participation, the documentation will be good.
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
I think one of the most useful parts of a good design is a really good overview or statement of intent that should include logic trees / flow diagrams and a few other diagrams. It should be mainly written, in good, concise, accurate, English and should make sense in it's own right while not being too long or overly technical.
You know you've got it right when you can grab anyone with a logical mind and, though they have no contact with the project, they can read the overview and know what the project is trying to achieve and have a vague idea of how your planning on doing it.
These are very useful when a hole appears in the meat of the document because from the higher level overview you can see the direction the missing bits would have taken had anyone had ever written them.
Other than that there are a lot of good suggestions posted here, particularly on the need to update documents.
In order to save our freedom it was necessary to destroy it.
- 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.You'll find it useful to have an addendum to the design document:
A user.
We work in teams of 5/6 people + one user/business expert.
That way when we hit inconsistencies in the design, or missing details, we turn and say "Bruce, does this mean X or Y?" (and he usually says "Z").
Note: They aren't all called Bruce. Yours may have a different name.
If you want a further idea about our working practices, take a look at an article I wrote here
My Journal
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've worked as a programmer, project lead, project manager and have eventually found my way to enterprise architect. I've seen a plethora of software development projects, in all stages from beginning to end. What stands out most in documentation is the need for various levels of detail. A good design document will provide at least three levels of detail for every section. The first and highest level is a summary of business requirements that are being met with descriptions of associative functionality, almost in a "the business dept needed THIS and THESE functions are designed to meet that need". This highest level is for the project members who are neither technical, nor intimately involved in the project other then as business leaders for requesting department(s). The second level of documentation should be designed with QA in mind, detailing data sources, structure and flow. Diagrams are a natural fit in this section. The third section of documentation should deal more with the architectural design of the code itself. This includes the explanation of complicated algorithms used to solve problems which are also explained. This level of documentation is difficult to come by, but it the section most usable by the programmers themselves (well commented javadocs is an example).
The challenge with this is that to get this kind of detail, you will require a number of authors, and that is rarely a priority or even a possibility of team put together to develop software against both a budget and a timeline.
I wish you luck on your documentation efforts.
"Everything in the universe is clouded by the impositions of the mind"
The design document should feature explanations of your architectural patterns. Those are less likely to change in the short term and therefore makes the document less problematic to maintain.
:-D
Let's say that you are writing an MS.NET Windows forms application and you have the following dataaccess strategy (which may or may not be 100%, though that is irrelevant)
- write stored procedures,
- generate datasets,
- encapsulate the datasets in a business object.
- implement typical NELS features in the business object
- databind GUI on top of that.
Your design document should contain one or more system sequence diagrams, and a class diagram to communicate to other/new developers the key aspects of how this pattern is implemented and which consequences it has. Document the stuff that represents core design desicions, and not all the stuff that is evident from the code.
Don't hesitate to use descriptions such as "Adapter", "Bridge" or "Abstract Factory" in your design document. It might actually help a future co-worker.
Do not Ctrl-C Ctrl-V chapters in your design document to cover every single business object that is created using a pattern. Mention special cases only if they deviate significantly.
Document complexity and not the simple stuff!
A complex security model, an algorithm to calculate optimal scheduling are both examples of things that should be given special attention. Use the appropriate documentation techniques in each case.
Document a specific feature type or an idea behind the application as opposed to describing how these ideas apply to every single class
Document a design decision even if you know it could be better! A lot of developers make design decisions that they know have deficiencies. Either due to incompetence or lack of time (or both). It may even be these design decisions that are most important to document(since really good designs often are more selfexplanatory). Many developers choose to leave such low-quality decisions silently undocumented because their gut feeling tells them they're on thin ice.
I have no idea how many hours I have spent trying to figure out whether I can change some spaghetti code or whether there is som hidden meaning behind those 20 layers of nested if's
"...with a cheese grater in a couple of steps"
where is that step?
This space is intentionally staring blankly at you
Read the code.
It is, unfortunately, the only current and correct accurate description of the way things work.
Documents rot because nobody is measured by the document accuracy or quality after version 1.0 of the document.
is competition good, or is duplication of effort bad?
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
What is GOOD DESIGN? A design document that 1. Adds value/understanding of the proposed system to the developers 2. Can facilitate a test plan 3. Can adopt change 5. Etc. If it does not satisfy point #1, then it is completely worthless. Note that UML documentation is merely a notation; a bad design in UML is still but a bad design. Its unfortuate that you had a UML NAZI as a prof. There is a perfect example of one who is in academics because they cannot hack it in the business world. I recommend you switch to a more prestigious university. Software Engineers use engineering principles yes; designs which are tried, tested, and true. Whereas, Computer Scientists, when faced with the task of designing a system, will try to "reinvent the wheel". Futhermore, UML Documentation should only be written if it adds value to the projcet; if the UML documentation helps developers understand the system, then it should be written. If it doesn't, then it is completly useless!!!!. Any competent prof will pound that into your head, like a mantra. However, there it should be noted that modern Computer Science programs are interlaced with Software Engineering.
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
Software Requirements Specification - IEEE Std 830-1998 - IEEE recommended practice for software requirements specifications
n dt itle=software&letter=software&imageField.x=2&image Field.y=3
Software Design Document - IEEE Std 1016.1-1993 - IEEE guide to software design descriptions. Updated in 1998 IEEE Std 1016-1998
Software Acquisition - IEEE Std 1062-1993 - IEEE recommended practice for software acquisition. IEEE Std 1062-1998
Found by searcing IEEE:
http://ieeexplore.ieee.org/xpl/standards.jsp?fi
Those are good points. Similar stuff is adressed by a few other good posts - but everyone is assuming the system has databases, a GUI interface etc.
Lots of software has none of those, not even a user interface. You also need things like:
- Design goals: what are the objectives and constraints
- Requirements (can be just references) and how they affect the design
What keeps me going is my inertia.
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've been on a few where something got changed // increment i
for a very good reason, but the reasoning was
lost when the staff left, or was forgotten with
time. I like to see comments on WHY things were
done, not stuff like:
i++;
-- Programming with boost is like building a house with lego. It's a cool but I wouldn't want to live in it
I've worked on many projects, some with documentation, some without. I'm currently designing a point of sales system for my employer and trying to get information from him is worse than pulling teeth. At least with persistance, the teeth come out. I've gone days without getting a straight answer out of him, often without being able to get any kind of useful answer out of him at all, so I resort to implementing whatever the hell I want.
Sometimes that backfires and I have to rip it out, but for 99% of what I've been doing, it stays in. To make it more interesting, development and deployment are simultaneous and I can't exactly withhold adding new features for months on end before letting loose a new version that could break a bunch of stuff. I average a release every 2 to 3 weeks.
When I started working for him, I was going to do it right by ironing out exactly what he wanted on paper then implement. I got about 5 pages of design before I realized it wouldn't work here.
Code documentation can also be just as bad. I could spend up to 70% of my time maintaining comments and function documentation, only to accidentally let something slip when I subtly change the behaviour of the function or the block of code.
I've always been pretty good at reading the code directly to find out what it does. It might be time consuming to figure it out, but as I see it, the time I save not maintaining documentation which over the course of a complex project will invariably become incomplete/incorrect, can be better spent figuring out what the code is actually doing. The code does not lie. It can be very misleading, but it does not lie.
If I ever did plan to write up documentation (non user guide) on this project, it would be a very simplified overview of the environment, the tools required, the source control used, the database backup and archiving schemes, etc, but to get into serious detail of why this feature belongs or not, in my opinion can hide the forest for the trees.
http://www.joelonsoftware.com/articles/fog00000000 36.html
Explains clearly how to lay out an actual like useful spec.
The design document should be the source code with a few big blocks of comment at the start of various modules and one readme file that tells you which source file to start reading first. The reason is that in the heat of coding, everything thats not source code is going to get lost, no-one is going to bother opening up a word processor and the only place you can easily write something and expect to find it again is in a comment. Also the only way someone is going to read your design document is if its in the section of code they're looking at. Diagrams and tables? ASCII art.
If your boss asks you for a formal document printed and bound, just write a script to dump all the comments to a file - you could even have a system to mark single line code-explanatory comments so that they don't go in the doc - then your document is always up to date.
This comment does not represent the views or opinions of the user.
You should have 2 documents only--an informal sketch of the design (possibly including addenda for fixed-in-stone interfaces), and a slick, comprehensive manual for the end user. All this UML and case use junk is an impediment to writing software. Software should be written in a military model, not a consensus or collaborative model. One project general who understands the whole thing, who delegates subcomponents. If one person cannot understand the whole thing, your project is dead already.
I spent most of last winter writing software for a major university. The specs were passed by a review board who were more concerned about the spelling and CAPITALIZATION than the functional points of the design.
Having 10 weeks to write the app, it took them 9 to decide on the specs. - I wrote the app while they were arguing about it. The app worked - they paid me..
"Straddling the sword of technology..."
For another point of view, check out http://www.ArchSynergy.com, click on the SEEM link. SEEM takes formal methodologies and wraps them with a more practical approach. We've been using it successfully on a variety of projects with excellent results. Of course, I'm a little biased... :-)
"Well, truth be told, I've not seen one since moving to the US. Real design work is rarely done, and documentation is something added on at the end"
Don't really know where you work, but welcome to my world! I have been a software engineer for 5 years now, and we do ASPECS, BSPECS, SRS's, Pre-Design, and Designs Docs. We do some prototyping sometimes in between to make sure it can be done, but most companies do design before code.
This is the thing I miss most about a design document. They go into details of all the specifications and requirements and fail to give the big picture.
Explaining why a requirement exists helps the person actually doing the design and implementation understand if you really need it to be this way, or if certain things happened to be a mistake.
By explaining why, you allow the designer and the implementor to solve the problem elegantly and well as they understand how each part of the system ties into the whole.
Many companies won't pay engineers to write documentation, i.e. give engineers documentation time. However, the PHB will have a requirement that engineers must provide documentation all the while looking over their shoulder to make sure they are writing code.
Too often documenation is only given the appearance and lip service as to the importance of the documentation all the while asking engineers if they can meet deadlines. Even if someone other than the engineer is writing the documenation often times the engineer is tasked with starting development before the design document is completed or yeah even started.
A software design document is primarily a communication tool. First step is to decide who you are communicating to, as what needs to be in the doc differs for different audiences.
For the purposes you describe -- to subdivide the implementaiton between people who were not part of the original design team-- you probably need:
* An understanding of the overall design of the system (what the system does belongs in a different document).
* An understanding of what each piece needs to do. What all the legitimate inputs it can expect are, and what it must do with them or in response to them.
* All the details of the interfaces between the components. Be analytic here -- you can't have too much detail as these are the places where you can parcel out work between the engineers. Anything not documented here is where the engineers will get it wrong and cause flat out failrues, rework or bugs.
Often, there are several levels of breakdown. Document them all.
Whatever you do, avoid implementation space. -- don't document how a subsystem is to work niternally, even though you need to understand it at that level to do the design work. I don't know any engineer that can successfully do this, but writing such text only wastes time, makes the document heavier, harder to read and understand, and ultimately won't make sense to some other person who has to implement that part anyway.
Then, when you realize that doing this is indeed what you need, but will take longer than management will allow you to do the design and implementation, pick a subset of what you really need that safisifies management to document, and leave the rest as verbal documentation to the other people who join the project. Factor in the size of the implementation team and document only the functionality and interfaces between the parts that different engineers will be doing.
My experience has been, working for a former Fortune 500 company (it may still be, but it stopped acting like one about 8 years ago), that there were no good design documents from anyone else that we could use as a template. Either someone had a document from a book somewhere that had the kitchen sink in it, or else it was such an atrocious and/or insufficient mess, that it was useless.
I think that what was really going on what that everyone was waiting around for someone else to come up with a good design document that could be used as a prototype. In the meantime we used the old standby, tribal knowledge, as a communication medium and design store. Thank goodness nobody ever got run over by a truck. ...no, actually, that wouldn't have been all that bad....
DT
Is this thing on? Hello?
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
In all the projects that I've worked on, the design docs are just there to satisfy management. Nobody ever actually reads them. ;-)
...
This is, of course, said in a "Ha, ha, only serious" fashion. I've written any number of design docs. But I tend to play them down. The reason is that, when you start implementing, you invariably find that you've missed a few important things. Sometimes this leads to significant redesign. And this means a lot of finger pointing and recriminations, because you Didn't Get It Right The First Time. Eventually you can get back to the job of implementing what you now understand you really need, and maybe do a bit of rewrite of the design docs. But you've lost a lot of time playing political games. And in poorly-run organizations, your initial incomplete design will be held over your head indefinitely. So it's best to try to make the design docs "preliminary", with the understanding that you'll revise them as requirements change or serious problems are found with your platform that prevent you from building part of the design.
In a really bad organization, the design docs will be cast in concrete, and you must implement to the design, even when you can show that it'll be a disaster. But in that case, you start looking for a new job right away.
I've seen one case of a design that had a serious flaw, which the designers insisted was right. I implemented the correct design in parallel with the official design, with a runtime flag to select between them. When the first customers all rejected it because of the flaw, I was able to quickly "implement" the correct design. I was a hero with everyone except the design team, who discovered what I'd done.
The fun ones are where you can prove that the design can't actually be implemented at all. I've worked on a couple of those. I found new jobs pretty quickly
I've long been a believer in the rule that the designers should be forced to implement their design.
Those who do study history are doomed to stand helplessly by while everyone else repeats it.
Using GPL fonts!
See "Domain-Driven Design" by Eric Evans. (Addison-Wesely, 2004). I general, I recommend writing about the system from different points of view, using different types of diagrams, even if it means some redundant information.
One of the increasingly popular developpement technique is the Extreme Programming (XP) as envisionned by Kent Beck http://c2.com/cgi/wiki?KentBeck. It involves constant testing, not designing everything up-front, but rather progressively. A must read.
A design document is not the same as a requirments document. as a example see IEEE 1233 for a description of a requirements specification.
Design document is lower level. It shoudl describe how you are going to deal with the requirements. Perhaps its just that what you call 3 sections, is for some 3 seperate documents. Created and managed by different parts of a business sometiems.
I ask new starters to my projects to write or add to the "things new starters should know" document. That seems to help.
***You learn something Every day. And then you die.***
A few years ago I developed a large project in Visual Basic. The only design was a pencilled sketch of the User Interface.
As the deadline loomed, I sat down and carefully wrote an overview of the system with copious flow
charts. This then was the design document.
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?"
One of the real problem, IMO, with design documentation is that a lot of time is invested in creating documentation no one ever reads.
Certainly, some documentation of "how things work" is a good thing. And key parts like API's and interfaces should be fairly well documented.
But unless you're part of a team of 200 programmers writing Longhorn, resist the urge (or the requirement) to document every little thing in tremendous detail. Here's why:
* Designs change. If you're doing "adaptive development" (a.k.a. Agile, RUP, Unified Process, etc.), the design is never 100% final. Some things are solid, but some will change. Out of date documentation is in 90% of cases WORSE than no documentation if someone relies on it as "authoritative."
* Even if you're doing classing waterfall development (first we gather ALL the requirements, then we do ALL the design, then we do ALL the coding), it's still a fallacy to think you can document everything in detail in a way that won't change. Writing code usually entails some learning, and that will affect the design. Again, a great big document that covers "everything" will probably wind up having inaccuracies unless you're INCREDIBLY anal about updating it.
* It's expensive--it's taking a lot of developer time to document.
* Skillset issues--developers aren't tech writers, so a developer writing a design document isn't ideal. On the other hand, getting a tech writer up to the level where they can write good design is difficult.
The best principle is "write the minimum set of documentation needed to ensure interoperability with other necessary components, get the entire development team on the same page, and to ensure your ap can be supported going forward." More than this is waste.
Before answering the question, we all need to agree on a design and implementation framework. For instance, the one I use looks like:
Once the above framework is laid, the following definitions can now make sense:
Note that if the code is the spec, then there can never really be a bug, can there?
Being a student currently taking MIT's 6.170: Lab in Software Engineering, I would point people to this page: http://www.mit.edu/~6.170/supplemental-info/docume ntation.html
And to http://web.mit.edu/6.170/ for the general class website.
Hello guys!
There are a couple of projects carried out at a department at my university. Abstracts for them are available in English. Maybe someone would take a look at them and comment on them somehow just a couple of sentences. English versions appered only a few weeks before today. I'm just curious - are these projects of any interest? Here is the address of the department - http://is.ifmo.ru/projects_en/. There is one project completely translated to english - http://is.ifmo.ru/projects_en/elevator/
It should enable new hires to ramp up quickly. When nobody works on it for 2 years and it needs a small modification, it should be clear from the docs where the change can and should be made. All upstream and downstream dependancies should be noted so when something breaks you know where to make the update to keep the systems working with each other. See? It's simple.
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
Actually, you can think of the three sections as being collections of pointers. The introduction should point to the more abstract view from which it is derived. The second "design" section should point to a more detailed design-oriented view. The third "implementation" section should point to a more detailed implementation-oriented view.
It may well be that the different sections are written by different people, but those sections define a complete view of a given level in the project. A complete view is the key difference between projects that succeed and projects that fail. How a company goes about doing that is largely irrelevent.
It is also important to understand the difference between implementation details at different levels. If you're starting with a formal requirements specification, then your "implementation" could be a Z Specification. From the standpoint of that perspective, it is an implementation, even though it is not an implementation a computer could realistically use.
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)
See http://www.sei.cmu.edu
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.
You can't ask for a good "design document". No single document is going to be sufficient for transfering design knowledge to every developer and analyst on a system. You need to have a good design documentation PHILOSOPHY.
I've been an analyst and coder and now system architect on a number of systems. My philosophy is to create a baseline system model that is the starting point of every discussion about the system. It is generally not detailed enough to answer any question about the system, but the important point is that IT IS ALWAYS ACCURATE! This model is the starting point of every discussion. We then look at the decisions being made and we start on a more detailed model that is tailored to those. That model -- diagrams, text, etc. -- is generally not proper for any other decisions because it's not focused for any other decisions. You have to do it again for every significant decision making session. That may seem like waste, but there are two important points.
First, we ALWAYS start from an accurate model. Any decision made from an inaccurate model may be inaccurate, and that means improper design, coding, testing, and delivery. In other words, defects. If your baseline model is not accurate you've changed underlying business objectives. That means you have a LOT of work to do. It should scare people when your baseline model becomes innacurate.
Second, we deal only with the information that is important for our current decisions. We have an accurate picture without distractions from extra information, too much detail, etc. We all know we can't maintain a detailed model. Software changes too frequently and deadlines don't let us spend the time we might need to maintain a fully detailed model. And we most of the time won't need a fully detailed model, just enough to make the decisions at hand. So don't try. Keep just enough to start from and go just far enough as required when you need to.
So, in short, develop a system model that has enough detail to springboard your development process, but not so detailed that it's hard to maintain and that it carries baggage to discussions that doesn't need to be there. This model will become the paper that everyone recognizes and everyone carries around to meetings. When that paper is insufficient for your decision making, let your analyst or system architect work with you to get you a more detailed model. When you're done, throw that one away because it'll probably be obsolete by the time you're done with your coding anyway. It certainly won't be pertinent to your next decision making and design activity unless you screw up the one that brought it about.
No methodology will tell you to do it this way. But then, I've never seen any named methodology ever executed to its fullest. No one can afford to do it.
The point of analysis, design, and documentation is to improve the probability that any development task will be successful. Out of the box, no methodology can guarantee that. But, if you approach analysis, design, and documentation with this as your objective -- making development successful -- you can use any methodology you want and adapt it as necessary. If you know your business people, your developers, and your processes you can take any methodology as far as it needs to go to improve that probability of success.
- Sig this!
Good question. Unfortunately, what constitutes "good" depends a great deal on what the system is.
Assuming that you have a separate set of requirements in some form, a set of design documentation should answer questions like this:
My bias is that structure and interaction is best described with UML. My preference for technical documentation is a word doc that walks technical staff through key points of the model, with snippets of the model incorporated into the document. The word docs and the UML models work together to specify the system. This depends a great deal on the kind of software you are designing. A three-tier Java system will reqire quite different documentation than a COM-based desktop app. Some documentation just doesn't apply to one or the other.
UML is best kept at an analysis or logical level; in most cases, code is its own best physical documentation.
Assuming the system has a reasonable set of UML diagrams describing the structure and dynamic behavior, a walk-through document with good explanations can make things a lot clearer.
Why are you asking Slashdot? :) Yeah, I can afford the karma.
-- "In order to have power, I must be taken seriously." -Mojo Jojo
Whatever you do, can I suggest that you put it in a Wiki? This will give you some glimmering of a hope in hell that it will reflect the actual product you deliver some day.
All other design documentation gets admired right up to the point that the writing of the application begins, then lip service is paid to it. If that.
If you do accept my advice, make the first job of any developer or support person this: walk through the design of the application (or their part of it) with a current dev team member, and amend all any inaccuracies found during this process. They will thus learn about the application, and the Wiki at the same time. You get immediate feedback (in the form of their contributions) on their competence. If they get it wrong it's easy to revert.
Another benefit is that the history will allow you to see how the application evolved through time - some of those nasty hacks the support team curse will be easier to understand (and thus support) when they know the short term advantages, or misapprehensions that it resulted from.
And lastly a word of warning - I've only had limited success selling this to management; I've not tried it in anger. But I've read a lot of design documentation that didn't faintly resemble an application that I was expected to fix at short notice - so it's got to be worth a shot.
--- These are not words: wierd, genious, rediculous
in a design document is Good Design.
One thing that I've found that is necissary but often hard to do is getting the end-users or functionality drivers to sign-off on the document.
This gets people to agree to a certain set of design requirements, helps reduce scope creep or at least track the baseline, and it scares people into reading more of the document when their butts are on the line. It also helps get user buy in and especially when third parties are involved, a negotiation point.
At my workplace, a document isn't considered complete until sign-off has been achieved. You can design all you want to but if you can't get everyone involved to agree you're in for a rough ride.
...seem mostly meaningless to me except perhaps in a university or very large corporate or government environment where research is done.
I've never met a "Computer Scientist" in the companies I've worked for, since that title implies a mainly research-oriented role.
I've also never met a "Software Engineer" except for the few folks I know who have that title and are also EE's, but they tend to be involved in the design of firmware or other hardware components.
Most of the folks I've run into in applications development tend to be described by more practical titles:
* "Project Manager" typically does task and resource allocation and coordination, but often remains somewhat non-technical.
* "Programmer/Analyst" tends to be heavily involved in both the design, coding, and testing stages and approaches things from a technical perspective.
* "Business/Analyst" tends to be heavily involved in both the design and testing stages and approaches things fron a functional end-user standpoint.
* "Programmer" is usually someone who is very inexperienced, and who helps the Programmer/Analyst during the coding and testing phase and sometimes in the design phase. In time, they typically turn into Programmer/Analysts.
There are also sysadmin and database admin folks, operators, and a few others, but they aren't as involved with formal softwae development (though the writing of scripts, stored procedures, and other things can often be significant tasks).
Mainframe/UNIX Bit Twiddler and long time Windows/Linux Hobbyist.
The Theorem Theorem: If If, Then Then.
A good document design will include the pecker tracks of every swinging dick that touched it.
The best description of my role over the years has been "programmer/analyst". I do requirements gathering, technical design (usually in conjunction with one or more end users or user reps), coding, testing, documentation, and support.
There isn't much complex math involved at all unless the applications I'm writing involve complex equations, or unless some of the solutions involve some form of mathematical computation.
While I respect people who have my qualifications and perform the types of tasks that I do, I've always considered "engineering" to be a somewhat more rigorous discipline.
Mainframe/UNIX Bit Twiddler and long time Windows/Linux Hobbyist.
The Theorem Theorem: If If, Then Then.
The ideal design document is the one you didn't have to write because you were too busy delivering well tested, working software to your customer. This is a lot better than the 300 page design document (which the customer in truth doesn't give a damn about) that you deliver only to have the requirements change 20 times, which are still incomplete, which lead to your project cancelation. I look at it this way: typical software development lifecycle assumes not only that you can know everything up front, but that you make the right decisions with the information. Dispite more than 30 years now (see The Mythical Man Month, F.P. Brooks) of repeated demonstrations that this doesn't work, projects are still too often structured around this flawed concept. A lot of Agile approaches discard this ritual or at least put a reasonable devaluation on it.
Take a look at Agile Manifesto for more info.
*** Sigs are a stupid waste of bandwidth.
It takes a lot more design time and effort to make your underlying design flexible enough to handle many changes. But, that design time and effort costs money, money that no one in either management or on the customer side is willing to pay. It also means that once a design has been settled on, implemented, and fielded, major rewrites will almost never happen. The attitude is "it works, it's making us money, and the customer is mostly happy with it, why change?" Unfortunately circumstances arise where the code no longer works due to outside changes (business rules change, operating system upgrades, customer requirements change, etc.) but still no one wants to pay to redesign based on the new environment.
.NET on WinXP with Oracle. I'd really like to see a design flexible enough to accomodate that kind of change!
Plus, a "design written with change in mind" can only accomodate so much, case in point, the project I'm working on currently was designed and implemented on Solaris with Sybase and Motif, and the customer wants a version in Visual Basic
By the taping of my glasses, something geeky this way passes
Three words for you: bottom up design.
The obsession with design documents is a dogma that refuses to die. But it should.
It is folly to think anyone can sit down and plan out all the important parts of a complex piece of software without actually building and testing the ideas first.
You won't find your faulty thinking until you try to build it. So the goal should be building a working prototype as fast a possible. Using a powerful, high-level language makes this easier.
Start by building the primitive pieces you think you'll need, and continue by combining primitive pieces into higher level pieces. You'll frequently realize that some of your pieces need to change in order to fit together nicely, but the changes are small and local. That's the whole point.
You will change your design over time, if you want it to be any good. So don't waste time on elaborate design documents, and write your software with changeability (and as a corollary, readability) as your highest priority.
"The danger is not that a particular class is unfit to govern. Every class is unfit to govern." - Lord Acton
Mainframe-based transaction systems, specialized apps like aircraft gross weight and optimal flap and thrust calculations, weather/ACARS message retention and distibution, etc., and now specialized application gateways between government systems.
Also a certain amount of systems software and utility development.
Not a lot of "database" work. We mostly use flat files or specialized transaction-system file types that are designed for high-speed access.
Mainframe/UNIX Bit Twiddler and long time Windows/Linux Hobbyist.
The Theorem Theorem: If If, Then Then.
As ciroknight pointed out, design is fluid.
In just about every major project I've worked on, the programmers discovered that writing to the spec wasn't feasable. Yes, we had a process to deviate from the spec, and yes we got permission to do so, but real-world time pressures frequently kept the spec from being kept up to date.
Not everything that is worth doing is worth doing well or correctly. Engineering is the art of making this judgement. A GOOD engineering process will at least go to the trouble of marking an out of date document as "out of date" so nobody gets burned by it in the future. Check that - a good engineering process will prefer to keep documents up to date, and only abandon that requirement when economics demand it - and then they'll mark the documents as stale.
Knowledge is how to play a game, intelligence is how to win, wisdom is knowing what game to play.
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.
I've worked in universities, where programs are written to further research goals, and in commercial companies. In universities there's no pretence: design and implementation happen in parallel; you write the bits you know how to do and gradually fill in the rest. In industry, this is unacceptable: the design has to be done first.
But - surprise! - it doesn't work like that. In industry as in academia design and implementation are done together. The difference is that industry pretends that it isn't true. Design documents are written that are accurate for the well-understood bits, and waffly or absent for the other bits. Provided that the same team does both design and implementation, this doesn't matter: it's just a harmless fiction. But if you have to implement from someone else's design document, the fiction is exposed.
Yes - thats what you are missing : Change control. It is used to track changes from a known baseline. Your known baseline is the set of requirements that you started from and any changes to that has to be estimated for, designed for and implemented without losing sight of the fact that this is a change - and not part of the base. What you are advocating is throwing out the (good) development methodology baby along with (bad) fact that requirements always change bathwater.
There is no such thing as luck. Luck is nothing but an absence of bad luck.
I've found keeping it on a wiki helps to keep the design document more current than it otherwise would be.
Its just so much easier to make minor changes when you have 10 minutes to spare.
One rule I used to use: before I would assign a design to a team to even think about coding, it had to be "cogent," by which we meant:
- Every word/term/acronym in it had to either
- Be listed in the Oxford English dictionary in the intended sense
- Defined in the design document's glossary
- Defined by reference (e.g. a URL or RFC#) within the design document and so indexed
- Ditto for file layouts, protocols, etc.
- Conflicting acronyms were not allowed (AI means something very different to a farmer and a game developer; if they are both going to be using the document, it will have to be spelled out).
- Any objects or processes alluded to in the document had to be fully defined within the document or by reference ("the EOM batch job"? Whose, HR's, Finance's, or the cron-job-of-holding the development team owns?)
- Any subjective criteria (e.g. "reasonable response time") had to be quantified.
- Any subjective criteria (e.g. "an atractive layout") that could not be quantified had to be tied to an individual or group that would sign off on it.
- There had to be a decent index
A good test would be to give it to someone reasonably intelligent who knows nothing about the subject, and let them red-pen in their questions.--MarkusQ
Don't do it Unix-style, or Linux-style, or even worse, javadoc-style.
These 3 approaches cover how all the nuts and bolts do their thing. That's good, and it *is* really bad. When I approach an existing system, I want a high-level description, which get broken in successively lower-level ones, until I get down to nuts'n bolts.
That's the difference between facing a forest and a whole effin' bunch of trees.
You're not old until regret takes the place of your dreams.
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
(cribbed from other comments, man ya'll are wordy)
...there are likely some good & useful things to be written about the requirements process, but i gotta go. have at it!
works for small to large projects, succinct version:
requirements -> design -> implementation
design phase produces separate functional & technical specs
methodologies are tools to be used, not rules to be followed!
everything is closer than you think.
There basically 3 things to be covered:
... yes ... I see that ... but why?
What
What is the software about, what are the functional requirements? This leads to input for the developers and to input for the user documentation (and maintanance documentation).
How
How is it supposed to work internal, that is a design about code structure, more about this later?
Why
Why is the code structured like it is. Why are technical solutions chosen, why got others rejected?
More important, when the sysem get changed you will see RCS/CVS logs like: changed the datastructure, field X from pointer to reference.
Hu hom, why? The why is usually missing.
Regarding the How I would assume you have at least 3 if not 4 levels of detail.
1)
Very high level design based on components. Every of the components or bigger subsystems of about 10 components should be documented again in the What, How, Why structure. How do subsystems communicate, which external resources do they access.
Technical issues like "we have choosen CORBA" and this "...." are the main (architecture) patterns we use, belong on this level also.
The architecture of the system below this level should be technology agnostic anyway.
2)
Every component should have associated the business rules or use cases it realizes. Again it should describe what it does (see rules and use cases) and how it is done (how do classes/sources realize the requirements).
Remeber a lot of WHYs probably answer the questions about: oops, why is it done that stupid? Hehe, probably there was a reason. If not its probably stupid indeed.
3) On this level now we are basically on code documentation level. Java Doc etc.
Again: don't forget to include a Why here and there.
This loop exceptionaly goes to length_of_array -2
Besides this documentation you likely have an over all technical and/or architecture document.
Also, like others have mentioned, a DB schema might be interesting, I however would associate it to the number 3) above.
A possible 4 is low level code documentation if tricky algorithms (sorting by counting) are needed or protocolls (my own subset of TFTP commands) or standards (hand optimzed DSE encryption).
Finally:
Intersting allways is a log where every major change and descission with a "what" "when" "from" "to" and "WHY" is recorded. Like a SCRUM backlog. Or simply a "Oppen Issue" list with resoltions, best of course in an issue tracker.
I left open in which way you do that. *I* would of course use use case diagrams and component diagrams (UML in other words)for the very high level. Going down via package diagrams (one per component) to class diagrams if technical issues are important. OTOH the latter often is not relevant IMHO.
angel'o'sphere
Cost free eBook I read (by iBook/Kobo/Amazon/ObookO/Gutenberg etc.): "The Green Odyssey" by Philip Jose Farmer.
>I've been writing software professionaly (sic)
That's professionally.
Luckily you haven't been writing the manuals.
CAN EDITORS PLEASE CHECK THE POSTS FOR SPELLING??
They will never know the simple pleasure of a monkey knife fight
Mod Parent Up. Wiki is a godsend to software development. The only problem with most Wiki technology is a lack of version control that is available in more sophisticated content management systems such as plone.
Key: Make sure the functional spec is exactly what it needs to be. If this means coaching your users on what you need from them, so be it. It'll be a heck of a lot easier than the back-and-forth that usually results.
I've recently been dragged in as the liaison on a project that had little to no functional spec. And because of it, we've got a lot of tension between the programmers and the end user in trying to get the job done. As far as the programmers are concerned, they've done their job because the code is exactly what was "requested". From the user's perspective, the program is entirely unusable.
Maybe I go overboard on the f-spec part, but if the user communicates exactly what they expect to see, the programmer has a much better idea of what they need to do and how best to do it.
F-Spec
(1) The "Here's what we're trying to accomplish, ahd here's how we think it'll work" fluff.
(2) The "Here are the parts we need, and what we think they'll do when we see them/click on them/enter stuff into them."
(3) Followed by the "Here's what CANNOT happen based on what we see/do/click."
(4) Have the user list stuff as
(a) Critical
(b) Desireable
(c) Absolute minimum allowable
(d) Ideal
(e) Totally unnecessary
(5) Make sure the user explains what they expect to do with the output of the program. Does it feed another program? Is it the be-all/end-all of programs? Is it a "nice thing to have"?
Given all this stuff, the design spec is much easier to build, or at the very least, more accurate.
Check out the Capability Maturity Model by SEI out of Carnegie Mellon. While it doesn't tell you exactly how to structure a design document, it does help dictate process and repeatability throughout the entire lifecycle. It's not just the design document that's important - it's how changes to scope and budget are managed, how costs are assessed, how not only technical designs are documented but how business requirements are discovered and recorded. And, at the end of the whole process, you need to review all of that with all the stakeholders to find out where things fell apart and how to improve the next time. The goal is not just to have a single, good design document for a single project - you want to be able to consistently, repeatedly deliver the same (high) level of quality using the same process. Doing that is more than just a design document format, or using UML, or having a good project manager - but all of those things contribute to ending up with a good design.
Crazy Cheap Domain Hosting!
There are three forms of documentation. The first describes what the product does, the second describes how it does it from an abstract point of view and the third describes how it does it from a concrete point of view. The first is the requirements document. This document should be readable (and read) by everyone from your CEO/President down to your Secretary (oh sorry "assistant" as secretary isn't used anymore). It states that you have A and you want it to do/be B. The way to get to point A from point B is by developing and using the Widget. Any modifications to this document after the coding process has begun requires signoff by the coding project lead (not just the technical manager) and anyone else you may desire to be involved. If your product managers (not project - product) attempt to put anything about HOW you the widget to work kill them. They are not software developers. Often times they are trying to "help" you because they know of other projects that are in the pipeline. Again, kill them. Those projects may never see the light of day yet would cost you X amount of development time to put the hooks in for it. The second is the technical specification document. This document is seen by the developers primarly. Anyone else would just look at it and be confused as they well should be. This is an abstract view of the Widget in its development form. Objects are described in this document and how they inter relate with the other Objects (and/or data). However, no code is included in this document. Even pseudo-code is a no-no in most instances. However, there are exceptions to this rule. Your lead architects and technical project managers create this document. Everyone on the technical side should read it but the coding team are the only ones required to read it. The coding team gives an estimate on how long the project will take. (Hopefully this estimate can be peer reviewed by another team). Again this all should be done before ANY code has been written (existing code is of course an exception). At this point, code is written and documentation is peppered thoroughout the code. With Java or .NET you can put comments in the code that you can then use to create documentation. This is ideal. Any other kind of documentation about the code itself is useless as it will rarely be used if ever. Again, there are possible exceptions such as Class Diagrams. If you do peer reviews of code before check ins then the peer reviewer should also review the documentation in the code. If you do not do peer reviews then the a portion day after release (or whenever you do a post mortem) should be dedicated to code documentation review.
New developers on a project should read the requirements document. No exceptions. The second document is actually optional and used for reference. And of course, the third is available for reference and will be used the most (by developers).
Instead of providing a checklist, I'd suggest a mental approach to writing a design document. Consider who's going to be using your design - developers working on the piece you're designing, developers working on other nearby pieces, QA engineers, support, documentation, etc. Now, imagine you're in a room full of all those people and you have to explain/justify how the code is put together. For best results, imagine that the audience is just slightly hostile. Now, try to anticipate all of the questions they're going to have. Is somebody likely to suggest that you should have used a particular framework or technology? Explain why you did or didn't. Is there likely to be a performance weenie involved? Explain what you expect the performance to be under different kinds of load, and what will affect it. Security weenie? Explain what kinds of authentication/authorization will be involved. For anyone, explain what kind of diagnostic or debugging capabilities will be provided. Is there a particular kind of danger to which this type of program is particularly vulnerable (e.g. loss of connection for a network app, missed deadlines for A/V, data corruption for storage)? Explain what steps you're taking to prevent or ameliorate it. For extra credit, offer QA some ideas for testing difficult cases. If you do a good job anticipating what kinds of questions your constituents/reviewers should ask, you'll end up with a document that will not only sail through review but will actually be useful when it's all done.
Slashdot - News for Herds. Stuff that Splatters.
http://readyset.tigris.org/
I use this at work and it's a dream.
From the site:
"ReadySET is an open source project to produce and maintain a library of reusable software engineering document templates. These templates provide a ready starting point for the documents used in software development projects. Using good templates can help developers work more quickly, but they also help to prompt discussion and avoid oversights. "
Posting this question here is like going to a pharmacy for a medicinal diagnosis. They like to imagine they're docs, and might even play with the same toys, but in all actuality they're the ones who didn't cut it as the medicine man (or in this case computer scientists).
I recommend going to a local college or university and speaking with a couple of professors there about design documents. As you may have noticed there are a bunch of Slashdotters here who know a little more than crap about program design but like to comment on it as if they do this everyday. If you haven't picked up already they're the pharmacists or the nurses at hospitals - useful but not specialists.
Alright , hit me.
We have a statement "code is design" (which I agree with) and a response from the old guard. Requiremnts, Design, Code, Test. Neither side quite capture the problem. Evolutionary development is the ONLY way. Start small, prototype all aspects of the problem, incorporate improvements in understanding - repeat. Tom Gilb has been saying this for twenty years now.
The monolithic design, code, test has so many failures attributed to it, I am amazed that anyone would still use it. At least when the Tacoma Narrows bridge collapsed engineers changed the way they design bridges - software engineers still proudly proclaim that they use the "Tacoma Method".
Part of the problem is that we are still developing systems based on 19th organizational princples. The "Designer" who is above mere mortals and is able to forsee all and every problem. The minions who are supposed to code in the way that Ford workers were supposed to build cars - with perfect ignorance. Get real!
At the end of the day, the professor and the PHB have similar goals. Keep employment and grow their powerbase wilth minimal stress. This is far more easily done by throwing around and demanding buzzword compliance (makes you sound cutting edge) etc and being picky about little details.
Engineering is the art of compromise.
Use Eiffel! :)
People seem to understand this in war, but they keep up this pretense that software can and should be spec'd fully before the first line is written. In the real world as opposed to the CS classroom, you iterate and evolve software. Anyone who thinks they can design a complex system down to the last bit is a fool. At best they will make stilted complex software forced fitted to an obsolete design document. Screw the fucking acronyms and design methology du jour. Natures already shown us how to develop complex system, its called evolution. Like it or not, your down to the last bit design documented software is going to evolve. Just as its about done, there is going to be a new sales requirement, just get used to it. Cut with the grain not against it. This is the real world, not a CS professors fantasy world. Thats not to say documentation isn't useful, however its better to document what really exists, than documenting a fantasy system, which then must be force fitted to that fantasy.
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)
I've worked at NASA, the DoD and a nuclear accelerator facility. Frankly, the code quality was minimal and if serious, usable documentation existed, it was because I wrote 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)
Two (completely different) reasons to have a design doc:
1) As part of the process of figuring out what to build.
2) To document what we have built.
If (1) then it's a part of the build process - you write it to get your ideas concrete for yourself and so others can review them, you may mention options you aren't taking and why, the results are fluid.
If (2) then you'll want references to the code that you've built to give examples, and also pointers of to key bits of code and a mention of what bits ended up more complex than expected and why, what bits of code to read and pay attention to, etc.
Many bad processes try to conflate these two documents. That wastes a lot of developer hours and results in crappy documentation.
If your aim is (1) then don't pretend you're producing good documentation for what the final system is like. Also realise that anything written before you coded and tested will be inaccurate by the time you go live because plans shift and change.
If your aim is (2) then you can write it much faster and better after you've finished coding.
Sean
I would kill for some people who actually want to do Q/A. All the people I see are "SysAdmin" wanna-bees or lazy-ass "coders" who don't want to bothered with details. Any tips on advertising for qualified Q/A people?
A "Computer Scientist" is a mathematician specializing in an obscure branch of mathematics. There is no "science" involved.
Describing computer science as maths is like trying to pass off biology as physics. Certainly at some level everything in computer science can be described by maths, (and in certain areas it is just maths) but in many cases the level of abstraction is so high that it's impossible to analyse it. Hence the science.
I've been working for a few years now, so here's my take on documents I found useful and that I really like to borrow stylistic elements from.
- The problem should be stated first, clearly. This usually helps someone reading the document to think roughly of their own solution first -- the rest of the document only confirms their hunch (if they're competent enough, i.e.).
- Avoid presenting low-level details as long as possible, proceed top-to-bottom in the hierarchy of abstractions in the system you are designing.
- Define all special terms and jargon in a separate section after the introduction.
- Use the right diagrams -- this is a tough one. Finding the right graphical representation to concisely yet lucidly describe something is the toughest problem I've had.
Agreed that design is fluid, but my point was that design is done before implementation begins. Thus, while design is fluid during the design process, it is over by the time programmers have started.
Your approach would leave you with approximately 327 documents for MS Office.
To find anything at all in them you'll need another document: An index. Good luck getting that down to 20 pages.
And 300 documents, 1 index? I know.. lets consolidate them all into a single bound volume.
No, don't call it a book!
~cederic
And I've been around a fair amount too.
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).
In my entire career, I see people try this time and time again. And it always winds up the same: destroyed family lives from the developers working 24x7 near the crunch time because of ambiguous requirements, customers that are unhappy because every time they change their mind they're given two words: "CHANGE REQUEST". CRs associate tremendous $$$ with any change, making it hard to deliver true "quality" if the market needs or our understanding of them is to ever evolve. Project managers that have very little real process control over what's going on and wind up as mere maintainers of spreadsheets, gantt charts, and earned-value analysis that have about as much accuracy as a tealeaf reader.
Your stated approach probably works well in enviornments where requirements are stable, and design work is so specialized that it requries rare subject matter experts. But I don't see those circumstances often.
There is a shift underfoot in software development akin to the one that manufacturing has gone through, from mass manufacturing to lean manufacturing, driven by Toyota's production and product development system. Gathering requirements , designing them, coding them, and testing them is "large batch" thinking that causes tremendous waste and inefficency because of the lack of learning, number of hand-offs, and amount of inventory (unimplemented requirements). Lean "Small batch" thinking is about small cycles of requirements, design, coding, testing, and refinement, with high levels of artifact reuse. Change is considered the norm in this process, while the product is in development. It's built into the funding and scope management structure of the project from the beginning , not bolted on as massive "shock trauma" that usually happens on projects with large requirements documents.
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).
There are some circumstances where a good requirements document is attainable, and useful. In most IT or product development circumstances, however, the number of changes required mean that requirements must be captured in a more fluid manner (whether they are use cases + a set of non-functional metrics, or features, etc.)
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).
Sorry, this is a fundamental disagreement. The code is the embodiment of the design. Sure, there is high-level design and low-level design, with different concerns. BUT, design is about direction. Implementation is about mechanism (do I use a for loop, a while loop, or a do loop?)
The algorithm and all of its exceptional cases are simultaneously part of code and the design because no matter how much paper you write, it's completely useless if that's not how the software was written.
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".
In a vacuum sealed world of hand-offs, this might be appropriate. But most of the time, I find that a classic requirements document are not the real requirements. There is loads of ambiguity in it, it requires constant iteration to clarify that ambiguity, and that iteration is best done through collaborative development between customers and deve
-Stu
Couldn't have said it better.
-Stu
Sounded like a dangerous cowboy until the last paragraph. Requirements are vital but never final. Yes. Tracing from requirements and understanding clearly requested changes to requirements is vital.
dnnrly, Take a look at the Truss Framework (http://sourceforge.net/projects/jdbgen/). This project started out because we had similar questions. The result is essentially design documentation for model driven architecture. Although the framework was originally intended for web-based database applications, we would like to hear other cases where it has been useful.
(In the same way, if you are building a bridge, you just don't care where they are going to place the restrooms in a nearby airport. If it's not relevent to what you're doing, why be burden yourself with the overhead?)
You also don't need an index. Remember, each document is linked (by means of pointers) to related documents. As such, an index serves no purpose. You'll always find things faster by following the pointers.
(Indexes are sequential. The document structure described is an n-ary tree. Trees are always superior to sequential systems for searching.)
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)
Trees are great when you're on them. However, the root of a tree for multiple documents is going to have to effectively be an index.
This might be why many books have a contents page and an index. Two alternate navigation routes, maximising the flexibility and accommodating imperfect initial information (i.e. what it is that you're looking for).
Obviously the answer is online documentation, in a fully indexed form, because your tree isn't as efficient as my google..
~cederic
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. I do work at a CMM level 2 company, doing designs, and I don't agree with this principle. First, though, I'll agree with a point made earlier: no one ever has the full set of requirements. Real-world schedules simply do not allow for it. When business people commit to a project, the money is allocated now, and you'd better be ready for the testing team to do their work sooner, rather than later. So, in practice: you start with the system architect gathering high-level requirements, and sketching a high-level design out of that. He then hands this off to the subject matter experts, so they can begin work on the design of each component -- but meanwhile, the architect fills in suggested low-level requirements, formalizes the document, and reviews it with the customers. He then revises the document as necessary, and passes the "near complete" requirements to the component designers, so they can revise their own designs. In practice, the customer will sit on the requirements for weeks before signing off on them ... even though they are effectively complete at this stage of the game.
It then becomes the job of the architect to merge all low-level designs into a single, comprehensive document. Why? Because ten (or even 3) documents are not handy. In any discussion, people need to be able to refer to a single document, or they waste time looking for the files. Central document management systems help here, but in practice, people will grab something they have printed out when they're headed for the conference room.
So, on to my suggestions for the actual design itself, rather than for the process surrounding it:
1. Use grammatically correct english. Someone else is going to have to read this; english grammar defines the tried-and-true rules for communicating effectively.
2. Use diagram(s) to explain the high-level architecture. Before people can absorb details, they need a contextual framework on which to hang that trivial knowledge. I prefer a data flow approach, where each object in the diagram represents an i/o or storage system; the arrows which connect systems should represent processes which move/transform data.
3. List key requirements, and explain how they are addressed by the architecture. It would be pointless to list everything, but some people work better from lists than they do from diagrams, and it helps to supplement the diagram with a list of key functionality.
4. Section the detailed design into chapters. Each design chapter should be a subsystem from the high-level design, and it should begin with the same sort of overview: a diagram of how the subsystem will function, with a list of key requirements and explanation of how you are meeting them. Many people suggest putting each of these sub-components in a separate design document; you've already had my thoughts on why they should stay together.
5. Peer reviews. Each section of the document should be reviewed by at least one other person, to make sure it is both clear and complete.
One thing to keep in mind as you write the design is that most projects involve trial-and-error; if the designer knew exactly the best way to implement every feature, then the final product wouldn't be innovative in the slightest. You're better off buying off-the-shelf for something that's been done before. Your project is unique, and odds are that some of the design choices are going to be inefficient (or just plain not work!) when push comes to shove ... or maybe you will discover during the testing phase that you have a hole in the security layer (you designed security, right?) you could drive a truck through ... or maybe when debugging a test scenario, you find your logs (you designed application-level logging, right?) don't provide the right kinds of information. Extensive re-writes of some key components of the design might need to be done.
Design is not documentation. Design is the blueprint, and blueprints make notoriously poor Owner's Manuals.
In theory, there's no difference between theory and practice. In practice, there's a big difference.
What the heck happened? All my newline characters got thrown out ... oh, woe is me! Why didn't I preview?
...
....
Testing
Testing more
I guess I should have switched from "HTML Formatted" to "Plain Old Text." Live and learn!
In theory, there's no difference between theory and practice. In practice, there's a big difference.
In a perfect world, design would freeze before implimentation begins.
The sad truth is that during implimentation, the market, and therefore customer requirements, change. A business has to make the decision "do we ship a higher-quality product whose design froze months before it shipped, or an up to date product that's less stable." Some customers want stability, others want the "latest possible" code. If you are selling to the 2nd group, design doesn't freeze until you ship. Even then, it doesn't freeze because you are probably constantly shipping updates.
The other reason design doesn't freeze is that during implimentation, you may discover that a given design doesn't work for some reason or another, or it's much more expensive to impliment than predicted.
A good project manager will keep on top of both possibilities and make decisions that are best for the customers, the employees (who don't like being worked to death), and the business as a whole.
Knowledge is how to play a game, intelligence is how to win, wisdom is knowing what game to play.
Some important criteria for a good design document:
- it should be the right amount of documentation for the job, not overkill
- it should accurately reflect the real implemented system
- it should supplement, not be a replacement for, real, working code
- when feasible, real working prototypes are better than documents
There's a world of difference between writing software for nuclear reactors and writing a typical "web page to display results of db queries". It's folly to apply the same standards to both.
In the latter case, when you're dealing with "pure" information systems (i.e., a bug in the system won't cause a reactor meltdown or a plane crash) requirements are often nebulous. Clients often don't fully understand their requirements until they see the finished product. So you're best off producing a working prototype or demo rather than a document.
if you have a requirement that you produce a polished "design document" before moving on to writing code, you're going to waste a lot of cycles on something that's going to become irrelevant and useless anyway. You can easily spend weeks perfecting a document that will just be thrown out once too many things change as a result of bug fixes, new features, etc.
that said, if your software is controlling heart monitors, airplanes, or the Mars Rover, you need to have a much more rigorous design and requirements process up front. My point is that you have to pick the right process for the job, though, and avoid one-size-fits-all "thou shalt write a long design document" dictates.
It is important that the design doc be started at the very start of the project, and that it continues to be maintained throughout the projects life-cycle.
A design doc must grow and change with the project. Without that it's totally useless two years down the line. I would include it with the project in your code revision system with regular check ins and tags.
I recomend that it includes information about any design decisions and why they were made that way. It is always painful several years in the project when you look at something and go: "Hey that's a weird way to do that. I know there was a reason, but I can't remember why..."