Pure Danger TechAlex Miller’s technical blog

1. Mittal Oct 25 2007 / 11pm

   could not open the document !!!
2. Josh Oct 26 2007 / 1am

   Both of the links point to a “.odt” file (which I assume is the OO Doc Template)… but no Word one :P
3. Nordine Oct 26 2007 / 2am

   The Word template: http://puredanger.com/techfiles/DesignNoteTemplate.doc
4. Alex Oct 26 2007 / 7am

   Oops! Fixed. The dangers of copy/paste late at night….
5. Stan Oct 27 2007 / 1pm

   I like your “what do they need to know” question. I’ve always wanted to put this first in the overview:

   _____ reads _____ to learn _____ so they can _____

   If you can’t fill it out, don’t go on. ;-) This seems to have a little too much of everything for everybody, which rarely makes good reading for anybody.

   “describe this feature/task to a greater level of detail than can be done in code” that’s very scary. This information will be LOST in the finished system if it can’t be said in code.

   Requirements and Customer Usage sections seem to duplicate things I’d usually have in another document, in terms the business folks can write, read, validate, etc.

   Priority 1 & 2 mean nothing to me. Hope they do to your reader. :-)

   Test cases restate requirements. Don’t Repeat Yourself. Maybe move them together into a two-column affair - requirement and how to prove you met it. Or - a really radical idea - write requirements as tests in the first place.

   I have to admit I haven’t had much success creating templates anybody actually uses. They look good for the Project Management Office, though.
6. Alex Oct 27 2007 / 9pm

   @Stan: This doc is more of a set of possible topics. Generally for a particular feature only some of these make sense. The intent is definitely to hit the high points for several audiences (tech, prod mgmt, qa) just enough that everyone can agree that what we’re building is what we need.

   For certain projects, this is not enough. For bigger, more critical, or less understood projects, you need to break these pieces out into requirements, design, test plans, etc. My personal opinion is that I’d rather undershoot and review than overshoot and waste time. I’ve found similar templates like this to be a great compromise point.

   The code is always the ultimate description of what the system does, by definition. But I find it is often not the best medium for a descriptive rendering of what the intent of a large chunk of code is doing, particularly on a per-feature basis. An ideal would be to have architectural docs that describe the overall system structure and per-feature docs that take a slice out of the system to explain a particular feature. In both cases, pictures are gold. Neither of these are easy to bleed into code. In practice, I find it unlikely that either of these are kept up to date. In lieu of that, having a statement of the original intent (and rejected alternatives) can be a gold mine at a later date.

   Sure, it’d be great if reqs and customer usage existed in other docs but in my (limited) experience they don’t, or at least not in enough detail. Admittedly, my experience tends toward the lightweight software startup world.

   P1 = must have, P2 = nice to have, P3 = stretch but unlikely.

   I do not expect a full test plan in the testing section. I expect a description of how (at a high level) testing will be accomplished, maybe a list of test ideas from a brainstorming question, existing system tests that can be leveraged, etc.

   I’ve used similar forms of this template in two previous jobs successfully. I’m happy to work in a company small enough that the idea of a PMO elicits a hearty laugh.
7. LudoA Oct 29 2007 / 6pm

   Could be helpful, although a template to help customers explain their needs/what they expect of a feature/… would be even more useful, IMHO. But I guess that’s too project-specific…

All content © 2005-2008 by Alex Miller

Entries RSS Comments RSS Java 7 RSS Music RSS