[Framers] Questions about tech docs in an Agile environment (may be off-topic)

[Alastair Dent]

I would say that checkin comments on code should be written in such a way that they can be used for release notes. Force standards for the checkin comments. Then the build machine can be setup to extract the comments and spit out at least a text document containing the notes. 

'Quickstart' guides can be a good idea, as long as they are carefully targeted. I've seen requests for this sort of thing "Why can't you just write short simple guides like this, we don't need such big detailed manuals" when actually the 'short simple' guides were more in-depth, they just covered a very small topic and specific instance. If you model user interactions and target the key processes, yes I think it is possible. Structured walkthroughs of the use of the product can also be very useful. They are painful to write initially but then easier to keep up to date. As long as the product has good tooltips in theory less gui documentation is required.

-----Original Message-----
From: Framers [mailto:framers-bounces+alastair.dent=imgtec.com at lists.frameusers.com] On Behalf Of Pat Christenson
Sent: 27 February 2017 22:43
To: framers at frameusers.com
Subject: [Framers] Questions about tech docs in an Agile environment (may be off-topic)

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 at 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 listadmin at frameusers.com