Re: Communication yes, chaos no
> While this is generally good stuff, I must
> disagree with throwing the design documents open
> to continuous tinkering by all. If the design is
> changeable by anyone at a moment's notice, you
> have no design.
Everyone should be treated equal, there should be roles and
responsibility. If a coder decided a requirement was too hard
and deleted it, that would be a coder not following their role.
I certainly wouldn't want a designer re-indenting my code.
> We still need to have someone in charge of the
> design. Hoarding is bad, but ownership is good.
> The thing is, the documents should not be owned by
> *any* of the designers. Go back and read _The
> Mythical Man-Month_ again, and look carefully at
> the role of the project librarian. Code isn't the
> only thing that goes in the library; design
> documents belong there too.
If the project has a librarian, then yes, they can shepherd
the documentation. Most projects don't have anyone,
except maybe the designer keeping the documentation
together and organized.
> You can still have the approved versions of the
> documentation *available* to everyone -- this is
> good. But a gatekeeper and sender-of-warnings is
> needed to preserve order and allow people to think
> without having to check for changes every hour.
Obviously if the design is changing every hour, it isn't
ready for coding. E-mail, and/or newsgroups can be
used to warn or discuss major changes, and their
The current situation where there is a document handed
out, and your start coding to it. Two days later a
new document is handed out, it looks the same, but
somewhere in 35 pages there is a change (no they
didn't use change bars, that'd be too easy, besides
they make the document look messy). Then about
release time one of the designers looks at your
user interface, and says they changed the second
screen, and moved it to 4th screen. You ask who
and when, and he shows you a copy of the design
document dated a week after the one you are using.
They didn't ask you to the meeting to discuss it
'cause your were behind in coding, and they figured
you'd get done quicker if you kept coding instead of
going to the meeting. (I am not making these up
they have happened!)
> A point I looked for but perhaps missed, is that
> *everyone* who is expected to contribute to the
> product should be involved with the design
> documentation. Not in the design itself, but in
> the crafting thereof. Designers are solely
> responsible for the design, but they should have
> to hear the concerns of the other players as they
> do their work.
Including the users, and the support groups. Absolutely,
this is very important.
Re: if not visio, then?
> you propose not to use visio as a
> design and modelling tool because not
> everyone has it and you can get
> concurrency issues and so on - so what
> do use then? (suggestion - did you know
> that in visio 2000 you can save a page
> as a jpg/gif - or a whole workbook as a
> series of html pages with gif/jpg img
Keeping the editable format is important, this allows people
who work on your project to edit the work, keeping on, like
having the source to the programs.
XFig works pretty well, I use it for most of my documentation.
It outputs JPEG/PNG (and gifs, if so inclined) that can be
imported for web pages. It is as bad as visio though, in that
it isn't available everywhere. I am hoping the W3C's XML
vector graphic format takes off. But for now, yes there may
not be a great drawing tool for general documentation.
> one of the problems we've also had is
> when dealing with client-orientated
> software, often the client liason dude -
> the consultant or whatever - is involved
> in a large amount of correspondance with
> the client that he then summarises into
> documentation. sometimes small items are
> ommited and nobody has a record of this.
> so my suggestion is that per project
> create a public email folder and address
> firstname.lastname@example.org and that all
> correspondance is cc'd to that email
Use a Wiki, pick your favorite. There are a zillion of them
and you can organize things this way. Certainly using a
e-mail list is a good idea, with archives, for announcements
The dude and you can both enter what you find important into
the wiki, and you can keep your and his version around as
long as necessary.