Design Documentation
-
General question:Am I the only one working at a place that decides to write the design docs AFTER the project is done? (coding, testing, etc all done)
-
@Hellz99 said:
General question:
Am I the only one working at a place that decides to write the design docs AFTER the project is done? (coding, testing, etc all done)
I'm not sure. Probably not, but then you might be the only one working at a place that writes design docs at all.
-
@Hellz99 said:
Am I the only one working at a place that decides to write the design docs AFTER the project is done? (coding, testing, etc all done)
Before coming to Microsoft, I usually saw a slightly different process: the design is written, the project is started, and when we're done the design is "corrected" to match what we actually built.
Now that I'm at Microsoft, our process is confidential.
That's all I have to say about that.
-
Hey another microsoft guy, knew there had to be a few of us here...
Traditionally I find that design docs are a two part process. I like to tackle broad architectural concepts early, even if it's just a bunch of boxes and arrows. Figure out what parts will handle what aspects of the problem, the relationships between them...dig into key algorithms that will be important, what the communications will be like, etc. I don't want to spend too much effort at this point because a) the devs who end up doing a lot of the work want some of the design fun themselves, b) changing requirements, yada yada yada, c) Designs always change anyway.
Generally I'm aiming to avoid questions like "if you don't know where you're going, how will you know when you've arrived?" At least if I know there are 10 major pieces to build and 5 of them are small, 3 are mid-sized, and 2 are big, I know where to put my resources and when, and I have some sort of dependency chart I can use to pull all the pieces together at appropriate times.
Then as the pieces are wrapping up, either I or one of my devs go back and document what actually got built for historical/maintenance purposes. Hopefully it's fairly close to the original design.
But, yeah, MS has a different model (or several different models) that I can't say I really understand yet...
-cw
-
@CDarklock said:
Now that I'm at Microsoft, our process is confidential.
I'd guess this is their design document for Windows Vista.
-
@Hellz99 said:
General question:
Am I the only one working at a place that decides to write the design docs AFTER the project is done? (coding, testing, etc all done)
Brooks himself commented on how "essential design documents" are frequently generated automatically from the software, after it is written - so not only is this not unique, it's sufficiently common to be in the book.
-
@CodeWhisperer said:
Hey another microsoft guy, knew there had to be a few of us here...
Even with the confidentiality-or-death-by-wild-animals clause, I would expect Microsoft employees (which, thankfully, I am not) to make up a significant portion of the userbase.
But, yeah, MS has a different model (or several different models) that I can't say I really understand yet...
One theory is that they figure "If we can't do it right, at least we can make it impossible for people to post embarrassing things on websites, so our processes should be incomprehensible".
-
@Hellz99 said:
General question:Am I the only one working at a place that decides to write the design docs AFTER the project is done? (coding, testing, etc all done)
At least your place of employment is even *bothering* with design documents.
-
You might consider the argument against writing design docs before writing the code: http://c2.com/cgi/wiki?BigDesignUpFront
-
@Angstrom said:
You might consider the argument against writing design docs before writing the code: http://c2.com/cgi/wiki?BigDesignUpFront
There's a big difference between thinking through what you want to build & making some basic plans and "big design up front".
You can spend a year specifying in mind-numbing detail every aspect of system behavior...only to have it become instantly negated when someone wants a small but fundamental change...and there are almost always aspects of the system that don't become clear until you're actually building it. I would never suggest that level of design work.
But, understanding what it is you want to build, having a small number of 'box and arrow' diagrams, getting an innate sense for the complexity of each of the boxes and what sort of information flows along those arrows, then having a 1 page spec for each box... that's the sort of thing that helps you do good planning and to track the development of the system, it gives devs a place to start working and an understanding of where their components will touch other components, and it helps the testers know the breadth of functionality they have to test against.
Starting with nothing except a vague idea is a good way to spend the next several months hearing "we're 90% done!" over and over and over again.
-cw
-
@CDarklock said:
Before coming to Microsoft, I usually saw a slightly different process: the design is written, the project is started, and when we're done the design is "corrected" to match what we actually built.
That's probably the best way of designing. After all, once the program is written, the design is in the code.
