Re: Not quite a Functional Specification

["Ned Bedinger" <doc -at- edwordsmith -dot- com>]

----- Original Message -----
From: "Keri Morgret" <kerilists -at- morgret -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Wednesday, May 26, 2004 11:08 AM
Subject: Not quite a Functional Specification


>
> We have a software product (released and in the field) that is
being
> updated. We have an existing user's manual that describes how
to do certain
> actions, but we are lacking an internal document that simply
states all of
> the functions of the product.
>
> What I need: Help describing what this type of document is
called, and some
> advice on how to structure this document.

Hi Kerry--

Short answers:

> I'm getting stuck on how and if to differentiate between "stuff
you can
> do", "stuff that sits there waiting for something to happen",
and "stuff
> that is entered and is for [operator] reference only.

I would refer to the groups of stuff the way they're named in the
interface, possibly adding some analytical touches:
Personnel>data operations, Personnel>User-configurable Options ).
This sort of organization can be imposed by you if absent from
the design, or it might be documented in some broader conceptual
terms in a Design spec, if such spec exists.

> What I need: Help describing what this type of document is
called,

The definitive list of the functions the software performs would
probably be the functional spec, but might not make sense without
also having the Business/User/ requirements documentation, which
will tell you the reasons why each function is necessary.

> Any idea how best to structure this information so that it can
be useful?
> I'm currently using an outline format in Word to just get me
started and
> see how crazy things are going to look, but I don't think that
will be the
> best result in the end. I'm thinking a matrix in Excel?
Visio-type diagram?
> Other suggestions?

Visio, to me, is a good way to document the flow of things, while
Excel tabular information makes a handy, expandable list with
plenty of room to add columns, cross-tab etc for
keeping track of interactive elements in the interface, all of
the functions in the software, etc.  I would readily put it all
in a text document, or as hypertext in a browser,  as the main
deliverable, and I don't think usability would suffer.  If it
were strictly up to me (and not the end users) I would deliver
small databases with a GUI front end for many things I now use
documents for, and I think a software spec would work well as
relational data in 3 dimesions.

Ruminations:

> This document will serve a couple of purposes. First, we want
to use it as > the basis for a test matrix so we can test certain
functions of
>the software as we receive alpha code from the (contracted
off-site) developer.
> Second, we want to be able to have a record of the
functionality of this
> software for a large redesign of this software that will be
done by a
> different developer - a way to get them up to speed on what we
want, and
> make sure that nothing is overlooked.

I have a notion about how I might try to develop a complete
picture of the software, but it is more on the order of a
brainstorm than a roadmap.  From a purely utilitarian point of
view, and not wishing to seem scary,  I assume that (a) you need
this document of all software functions, (b) you've consulted
with your manager and the project manager and they can't provide
it to you, and (c) the manager is not disposed to interpreting
your
activities in this regard as officious and unnecessary.

I'm perpetually amazed by how unindulgent some managers can be
when
their tech writers innovate in areas traditionally reserved for
programmers!  You asked so I answer, but the memory of scorched
tailfeathers is persistent, and I want to share that learning
with you before I suggest this little walk in the light, OK?  Got
guts?  OK!

If you're on your own without any testable formal specifications
from the dev or management team, you could approach this as Black
Box testing.  (Black Box is the condition of working with only
what is visible, not anything that goes on internally in the
software). There's no assurance that this approach will do much
more than scratching the surface, but it is a view of the
software and could be useful in communicating with SMEs about the
deeper functions.

Unlike the Black Box test methodology, which tests the software
against specific requirements, you won't be able to state the
real requirements addressed by the software or strategize real
tests. So, instead of test results, this modified Black Box
approach to your software will produce a sort of back-door Black
Box spec (which is not a document type that you're likely to hear
about anywhere else).  Proceed thus, leveraging the existing
manuals and diverging or innovating as needed:

1.   Enumerate all of the interface elements, and what each does
when you use it, or displays passively while it sits there.  For
the sake of thoroughness, include title bar, status bar, and <Fx>
or other shortcut keys you know of.  ("Files menu drops down
showing five (5) selectable file operation:  Save, Save As,
..."),

2.  Document any logical or visual groupings in the interface,

3.  Test whether the software is applying data rules to input
(such as your phone number input testing)

4.  Test whether the interface (e.g., the reference areas) and
the user
reports return the same information you put in.  Document report
formatting.

5.  Investigate, gather information, and test how the
software stores the input you give it.  Dig around for the
program's external persistent storage, such as configuration
files, named pipes, flat files, or databases that the software
uses, and evaluate these in terms of how the program is storing,
retrieving, and using your data.  This could get into database
table and field identification, names and data types, stored
procedures,...in short, database documentation.

6.  Identify the design of the system that the software works
within, including local and remote (over the network) hardware
and other software necessary to the software's operating
environment.  You might also discover scripts and remote
procedures, used to initiate activity on remote machines or other
software.

Those tasks done, you'll then have a baseline of system,
functionality, and interface design for future discussion of
changes (either forward-looking proposed changes, or the changes
you're handed in a new rev of the software).  Of course, it only
represents what you could discover, and is not a complete
picture, and is likely to be complex. Still, descriptive analysis
is good and should reveal some of what the real requirements
should state.

As I said earlier, you can baseline the product this way, but you
haven't actually validated it the way a tester would until you
test it against the same requirements and design that were
addressed by the development team.

If you can get dev team reviews of your description, then they
should be able to fill you in on any missing
requirements/design aspects.  A really robust version of their
comments might include their functional descriptions or
pseudocode describing what happens internally (and remotely, if
applicable) for each user action in the interface, and any other
processing or functionality that goes on (encryption, for
example).  And they'll talk among themselves about how useful and
ambitious your work is, you'll be asked to attend development
meetings, and good feedback will reach your manager. Everyone
will remember the high water mark set by the tech writer who
wrote the spec by reverse-engineering the software in a black
box.  I tried to warn you.


Ned Bedinger
Ed Wordsmith Technical Communications Co.
doc -at- edwordsmith -dot- com
http://www.edwordsmith.com
tel: 360-434-7197
fax: 360-769-7059





^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content 
Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo 

>From a single set of Word documents, create online Help and printed
documentation with ComponentOne Doc-To-Help 7 Professional, a new yearly
subscription service offering free updates and upgrades, support, and more.
http://www.doctohelp.com

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.