RE: Documentation in Rational Unified Process; SoDA

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

Michael Collier wrote:

> I'm not sure what you're expecting to see from Rational regarding the
> production of end-user documents. The Rational process is for software
> engineering, and as we all know,  well-engineered software 
> has no need for
> user docs (or users, for that matter? -:)

I'm interested in how easy (or difficult) it is to integrate an end-user
documentation process into RUP, as it seems to have no built-in provisions
for one. By RUP, I mean the process Rational sells, as distinct from the
tools it sells to support RUP. If the development team (the doc department
members are considered part of that team, at least here) has an exhaustively
detailed process that doesn't address end-user document production, then
somehow I need to insert *my* process into the cracks. So I'm asking how big
those cracks are, and how many handholds there are on the cliff face leading
to them.

It seems to me that with such an exhaustively detailed process, there might
be little room for non-RUP-defined activities (like interacting w/ doc
people, producing artifacts that doc people need that aren't defined in the
RUP, etc.) to intrude. I'm interested in others' experience with writing
docs in a full-blown RUP shop that used most or all of Rational's tools.

[deletia]

> One thing to check for is some kind of traceability tool that forces a
> mapping of requirements and use cases to design. You may be 
> able to export
> some of this data to an office application and outline your 
> user docs from
> there.

My first impression is that the Rational tool suite provides extensive
capabilities for wringing the last drop of data out of a project in very
customizable ways, including the mapping you describe. At first blush, I'm
quite impressed and think it could be quite a boon to someone writing
end-user docs.

> What exactly would you like to see Rational (or products like 
> it) provide
> for the production of user docs? Perhaps a CASE vendor will 
> be willing to
> listen and implement something useful.

After I've evaluated RUP and its tools, and digested any input from this
list, I'll post a summary. And perhaps forward it to Rational, if they seem
interested. It seems to me that as technical documentation becomes more
recognized as an integral part of the development effort, process/tool
purveyors like Rational might want to address it with their products.

Thanks for the input,

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