Pat,
My company has also migrated to an Agile workflow. We had no choice but to fall
into a similar process. I read articles discussing concepts of documenting on
time with each sprint vs. waiting for maturity and documenting late. Our teams
run 3 week sprints and the expectation is that at the end of each sprint, there
is product ready to enter the release process (which means regression test to
mfg and staging final docs for publication). The reality is there are often
failures in testing and most sprints do not complete a releasable package, and
there are otherwise marketing activities that really control the public
release. Like you, we typically have large quarterly releases. Also like you,
we have avoided structured content so your story is of interest. I'm curious
how many products/manuals is a lot?
We use Jira to manage workflows and track development activity. We are refining
the fit between software and complementary activities, but the idea is that a
software task for a sprint must also correlate to a publication task (when
appropriate). Tasks can be bunched under a 'story' that defines all of the
activity to complete a particular feature/enhancement, and we are then able to
bunch our work accordingly and maintain a reasonable balance between the above
two concepts.
I have tried to optimize our content development efficiency by creating more
topic-centric, and less product/feature-centric deliverables that can be
packaged and re-used in whole across multiple product lines. There are some
specializations that complicate this, but the strategy has been effective. The
deliverables are packaged into individual PDF files that define a complete
document set for a particular product or product line. Some of these documents
are very product specific, usually hardware related, and most of the
task/reference content is more generic and can be reused for other products. We
also create HTML Help content using ePublisher (WebWorks), and that can be
context sensitive and embedded in our products as well as stand-alone on the
web. The Help workflow is nice because we can package source content chunks in
various ways to meet customer's needs. We also maintain a print publishing
channel for customers that prefer that (which is rare, but still remarkable)
.
>From this point, it is clear that we must look at newer techniques and embrace
>a new paradigm. To me this means much more than just structured content, but
>must include other aspects of the business and tie them into unity so that all
>forms of information are accessible and present ready-use. I literally see a
>unified system that all stakeholders, including the design engineers,
>marketers, field sales staff, service, and training folks all using to develop
>their content, internal or external, so that every bit of it is readily
>accessible and properly managed. And then you can open a certain amount of
>that up to a customer facing, self serving solution. The writers can then
>focus on the small details of making great content and not worry about any of
>the downstream processes.
OK, my manager suggests we look for a scalable tool just for our small writing
group. I've heard some suggestions we look at Confluence and this thread has
been my first exposure to Paligo. All the solutions look the same to me and are
all equally as mysterious as what benefit they actually provide. I can
understand the concept of structured content, and even DITA, but have no
insight into the nuts and bolts of their use, overhead, and real returns.
Sometimes the marketing seems to get in the way...
Thanks,
C
------------------------------
Message: 5
Date: Mon, 27 Feb 2017 22:43:16 +0000
From: Pat Christenson <pat.christen...@morningstar.com>
To: "fram...@frameusers.com" <fram...@frameusers.com>
Subject: [Framers] Questions about tech docs in an Agile environment
(may be off-topic)
Message-ID:
<f5399dd46ad57c408f913a837803c3e30f574...@msexchm81.morningstar.com>
Content-Type: text/plain; charset="us-ascii"
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
_______________________________________________
This message is from the Framers mailing list
Send messages to framers@lists.frameusers.com
Visit the list's homepage at http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com
