Documentation in a Rational shop--summary

[Brent L Jones <bjones -at- VersatileSoftware -dot- com>]

S'hey all,

Recently I posted asking for people's experiences producing documentation in
a company using the Rational Unified Process (RUP). As our company is
considering a move to RUP, I'm interested in the topic and have spent the
last week or so evaluating the process, its associated tools, and how it
might impact the production of end-user documents and materials. The
following are my conclusions.

1. RUP virtually ignores the production of end-user docs as part of software
engineering. 

While not surprising, it is a frustrating manifestation of the tendency to
discount the necessity and value of quality end-user support in the
industry. While this is slowly changing, many companies still don't realize
that quality docs save them money (fewer support calls) and increase revenue
(the customer is able to use the product more effectively, thus likes it
more, thus is more likely to buy upgrades and recommend it to friends). As
Rational appears to be a company dedicated to providing quality, complete,
end-to-end process solutions that encompass the entire development effort, I
find this omission puzzling.

While the RUP briefly mentions the technical writer as a worker (someone who
does something in the RUP), it is essentially a placeholder with no relation
to other workflows in the RUP. No specifically detailed deliverables, no
upstream or downstream dependencies, no specific activities tied to other
activities. By detailed, I mean having the same level of context and
guidance present in other "artifacts" (documents), workers, and activities
in the RUP.

The RUP essentially says "The technical writer produces user guides and
release notes." No definition of a user guide or what it should accomplish.
It says that the writer should start writing these guides "early in the
process." And that's the extent of it.

For a big, supposedly definitive process like this, it is a significant
lack. For me, however, the lack isn't necessarily a big deal. I'd much
rather have to modify my existing process, assuming it is robust,
repeatable, and effective (which I think it is), to a well-defined software
engineering process rather than having to accept their definition of how
docs get done effectively and scrap how I currently do it. If you're looking
for any sort of structure or process help in RUP to help you get your doc
processes up to snuff, however, you will be gravely disappointed.

As an aside, it seems Rational realizes the gaping hole in their RUP where
end-user documentation production should be. One of their RUP managers
stated that the next release of the RUP will probably have more information
and context for producing end-user documentation. It is due out sometime
before the end of the year. I'll be interested to see it.

2. RUP produces a software development environment that should make the
production of end-user docs much, much easier.

While not specifically addressing end-user doc needs, the process does
result in a lot of things that are very conducive to quality docs. By
stressing detailed requirements analysis and effective control of captured
requirements, as well as providing an excellent tool to support this
(RequisitePro), it makes it easy to find out what functionality the software
will evince in a clear and concise manner. This should be a real boon to
creating accurate documentation plans, as well as allowing a head start on
organizing the user docs and sketching in their topics.

The fact that the RUP stresses change management (and facilitates it with
their ClearCase tool) should be helpful as well. Changes to specific
components (such as interfaces) are very controlled and can be automatically
communicated to involved people, such as the technical writer documenting
the interface. I think this should give a real boost to the level of
accuracy in end-user docs. Also, changes to requirements can also be
automatically communicated to appropriate folks, so you'll know right away
that the customer has changed its mind and you need to scrap the data
maintenance section you were going to write, but that the "adding users"
section will entail a lot more work than you initially planned.

3. SoDA, the RUP reporting tool, provides a powerful and flexible way to
access the wealth of data and documents created during the development tool.

During the RUP, a substantial amount of data is created and captured
regarding the state of requirements, how they're being implemented, how
they'll be tested, what the system's architecture is, etc. Rational provides
a tool called SoDA, which works with Word and FrameMaker, to produce reports
on this conglomeration of data. It has a number of preconfigured reports, as
well as the ability to create your own report templates. Like everything
else in the Rational tool suite, it appears to be very powerful but has a
steep learning curve. I think its ability to retrieve virtually any data
captured during the entire development process should be a real boon to any
end-user documentation effort.

4. "Use cases," the RUP framework for requirements gathering and analysis,
seem like a useful concept. However, the use case method has been criticized
fairly heavily in a number of venues, especially at the level to which
Rational takes them.

This last is probably off-topic for the list. Just be aware that if you get
the RUP, you get use cases, as they're an integral part of the process.


Well, that's my quick two bits on RUP. IMO, YMMV, YYY. Any further
information appreciated, although given the number of responses to the
original question I suspect there aren't too many people on TECHWR-L working
in a Rational shop.

cheers,
brent
--
Brent Jones, Documentation Manager
Versatile Software, Boulder CO
brent -dot- jones -at- versatilesoftware -dot- com