[Sigia-l] UI spec document tool

[Chris Chandler]

----- Original Message ----- 
From: "Dave Collins" <DCollins at phoenix-interactive.com>
To: <sigia-l at asis.org>
Sent: Monday, January 19, 2004 8:26 AM
Subject: [Sigia-l] UI spec document tool


> We are reaching the upper limit on effectiveness of MS Word as a repository
> of our software UI spec. Our docs are about 125 pages, mostly wireframes of
> each screen with associated text.
> Word is getting quite piggish:
> - buggy, too much formatting gets unwieldy, app crashes or is
> difficult to cut/paste
> - margins and tabbing is difficult to keep consistent (every line can
> be set up differently, cutting & pasting carries all formatting, formatting
> difficult to see/manipulate/delete)
> - handles things like table of contents only so-so
> - doesn't handle wireframe art as well as we'd like, clunky, difficult
> to search/spellcheck, get bizarre artifacts (orphaned textboxes that refuse
> be deleted)
> - hyperlinks used to establish flow between screens often break and
> have to be manually redone
> - software is getting modular, would like to be able to mix and match
> modules form a master template intoa specific client implementation
>
> The one big, big pro for Word is its portability - that we can guarantee our
> clients can read it, manipulate it, print it, etc.
> The first, most logical jump might to be Visio, but that's a awfully light
> on handling text well.
>
> What do other companies use for a spec of this size/complexity?


Most probably use Word, it is THE STANDARD you know, (and like folk anywhere, when I say "standard," I mean you HAVE
to use it or you'll be treated like a pariah... but that's another discussion, sorry.)

I'm looking into InDesign myself and although I can already say that there will be some time/effort cost in moving to an
actual publishing system instead of the everythingbutthekitchensink approach of Word, it still seems worth exploring.

If you just need help wrestling with your current documents, you need to make sure that you are using Word in the best,
and really only proper way -- with STYLES:

http://word.mvps.org/FAQs/Customization/CreateATemplatePart1.htm

http://www.microsoft.com/office/previous/xp/columns/column14.asp

Last year, I was able to easily reformat over 200 pages of documentation using styles and macros, so it may not be too
bad for you. I can't stress this enough -- if you use Word for anything more complicated than email or meeting minutes
(and even there you'll find it helpful), you need to go to the exclusive "style" method of formatting your docs.

But of course, this begs the larger question:

Don't you know you're supposed to give up after 125 pages!!?

For my latest project, I wrote about 60 pages of spec, with inline wireframes in Visio (another tip: use "linked" not
"embedded" visio files, it's a lot cleaner to edit the Visio files with Visio for some reason, and it will keep the Word
file's size manageable... on the other hand, you need better coordination/file-management to keep the files together.)
and I'm pretty sure that the QA lead was the only person besides me on the project who actually read the spec.

My group is now trying to move to a minimal written documentation model... I can't wait to see how it turns out.

-cc