[Framers] Questions about tech docs in an Agile environment

[David Creamer]

I know you said not mention structured, but it sounds like it could be a
good case for DITA-writing style (which FrameMaker supports).
If you don't want to use DITA, extensive and very organized use of text
insets would work.

RoboHelp works in a similar concept to DITA in that it uses numerous Topics
that only contain as much information necessary to address that particular
topic. Topics can be grouped together in general categories (folders) for
organization.

David Creamer
IDEAS Training
ADOBE Authorized Instructor & Certified Expert since 1994
FrameMaker Certified since 1991, including structured XML
Online, on site, and classroom training

_________________________________

From: Pat Christenson <Pat.Christenson at morningstar.com>

My company has a very large suite of products and I'm the only tech writer.
Software is developed in an agile environment, with some products releasing
new features every 2 weeks. The largest product updates quarterly. I can
easily spend almost a month on its release notes. We are using FrameMaker
and publishing as a PDF.

In addition to keeping up with release notes (which are very detailed, if I
didn't mention that), I'm supposed to be writing user & admin guides for the
sub-products. The ones we have are hopelessly out-of-date.

With all this going on, by the time I finish a user guide, it is soon
out-of-date and there just isn't time to transfer material from release
notes to the user guide, repaginate, etc. and post it.

My team director and I are trying to come up with a more efficient way of
getting this information to the user in a timely way and write much, much
shorter release notes.

At this point, we're leaning towards the following:

  1.  Instead of long, detailed user guides, write shorter QuickStart
guides, covering the basics. Once the user has absorbed this, they can go to
the product's searchable Help to find info on a specific topic. (No one
reads a 75+ page user guide, right? They read enough to get started and then
search for info as they need it.)
  2.  Make release notes very brief-one or two sentences describing a
new/enhanced feature and a couple of keywords so they can search the product
help for the details.

Although several of our products have very basic Help, there is nothing in
place like we're thinking of.

So long story short:

  *   Are you producing timely documentation within an agile software
development environment? If so, how and is it working well?
  *   Is anyone doing something like what we're thinking of?
  *   What are your recommendations for tools? FrameMaker-to-Robohelp? Give
up on Frame and write in Robohelp? Something else?
  *   Can you quickly add new material (topics & steps) to an existing Help
system?

I developed a couple of Help systems years ago, using FrameMaker and
Webworks. I'm not sure if that qualifies me as a newbie since so much time
has gone by.

I will appreciate ALL your recommendations, whether sent to me privately or
posted on the list.

P.S. Please don't recommend structure. There's no way we're going down that
road for only one tech writer.

Pat Christenson