Design the manual first, the software last?

["Geoff Hart (by way of \"Eric J. Ray\" <ejray -at- raycomm -dot- com>)" <ght -at- MTL -dot- FERIC -dot- CA>]

Linda Sherman and her brother <<...are giving serious thought to
developing and selling a fairly large and complex software product...
One suggestion I heard years ago but have never actually seen used on
a software project was to write a prototype of the user's manual
/*before*/ beginning actually development of the product.>>

Given that this is the way software is supposed to be designed in the
first place (i.e., "let's start by deciding what we want to
accomplish before actually starting to code"), it strikes me as
nothing short of incomprehensible that software is developed any
other way. Most software does seem to begin with something like
a "functional requirements doc" (or various other names), then
rapidly diverges from the design goals ("creeping featuritis" is one
cute name I've heard). Creating the user manual first is a
particularly attractive notion because as techwhirlers, we often have
a far better grip on usability and audience issues than the
developers do; starting with an effective design, then coding to meet
that design strikes me as far more productive than building the
software first and only subsequently trying to figure out whether
it's usable. I've read (but can't recall where... can anyone
help?) that some companies have tried designing software this way and
had good success.

<<we have limited personnel resources and I don't want to
invest them on something that would be a waste of time.>>

It's usually a waste of time to fix things retroactively, and a big
timesaver to design it right first. "Measure twice, cut once", as the
carpenters say. You could probably accomplish the same goal simply by
creating and adhering to a decent functional specifications document.

<<Did it include screen shots, menu layouts, etc. and if so, who
determined their content and appearance?>>

I know that in two cases (two pieces of software I'm working on right
now), the developers came to me and asked how they could best
accomplish a set of tasks; acting as a user advocate, I came up with
an interface design that they liked and then developed code to
produce. How'd I work that particular miracle? I sketched out their
first attempt and my revision on paper and walked them through the
mouse clicks and keystrokes. My design dramatically reduced both, and
(probably what made the sale and got them to come back again for more
advice) also showed them how to reduce the amount of coding required.
Yes, I'm blowing my own horn, but not because I'm a rocket scientist:
with a little thought, they could have done the same thing, but
developers tend to fall out of the habit of thinking like users,
generally because they get too close to their software. And before
you ask, yes, we'll be doing beta testing to confirm that the
interface is efficient. It would have been nice to test the prototype
with users first, but...

<<Was the prototype used as a basis for the shipped version of the
user's manual, or was the latter basically written from scratch?>>

In both cases, we're documenting based on software that kind of grew
up out of nowhere based on a user needs analysis. Since we had no
formal software development or documentation processes in place at
the time, we're playing catchup. I'm hoping to move the developers
gradually to a prototyping approach (with user testing) followed by
actual coding, but I'm not optimistic this will happen soon. I get
the feeling that this sort of evolution is gradual, and that you have
to pass through the painful stages of doing it the wrong way before
you can do it right. YMMV.

<<Any comments, suggestions, advice, etc. would be greatly
appreciated.>>

You mentioned that you'd be doing this with your brother. Without
knowing your abilities, the best advice I can offer is the suggestion
that you find someone who knows how to manage the development process
and someone who understands marketing. In general, that's not a
developer or techwhirler skill (witness Apple's sad history and that
of many, many other high-tech startups), though YMMV (and often
does).
--Geoff Hart @8^{)}
geoff-h -at- mtl -dot- feric -dot- ca

"By God, for a moment there it all made sense!"--Gahan Wilson

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=