Structuring Help for Many Apps and Agile Development

[mark_anderson_us]

Hi Guys

I am starting to evaluate RH9 (with server) and am lookign for seom advice on structuring help.

We produce a management information system, which comprises 17 apps.

We have major release versions: e.g. 4.9, 5.0 and then sub builds (e,g. 4.9.0.23)

Most sub builds contain new features that require documentation. We do agile dev, so we are producing new builds every few weeks. This means we can't just produce documentation for major releases (e.g. v4 and v5). This is waht we do right now, but it means it's always out of date

My initial project is to setup the master pages and css and import the Word manuals into RH and do any necessary cleanup. We will initially publish web help and "printed" (PDF) documentation from this, but eventually want to link into our applications (initially on the help menu and them adding context sensitive help).

So if a user is running 5.0.0.23 of Inventory Management and goes to the help menu, I want them to be able to get to the documentation for that specific build.

So, from a documentation point of view, how do I manage all of this?

Do I put it all under one project or one project per app or per major version or build? My main concern is that we can literraly have 100's of different builds in use by customers, so if we change the documentation for feature X, all users on relevent builds get the updated documentation.

We are keen to get user feedback and improve areas that require improvement, so let's say a user says the documentation for setting up warehouse locations is not very good. This feature has been around since version 1.0, so we want to update it's documentation and have it available to all current versions (4.x and 5.x). Is there a way to setup the documentation such that I can flag parts of it to specific versions. Using the above example, I want users on all versions and all builds to get the updated version; however, if we change the way locations are managed in 5.0.0.23, how do I ensure that everyone on 5.0.0.22 and below gets version A and everyone on 5.0.0.23 and above gets version B? Clearly, I don't want an entire project for each build (e.g. 5.0.0.23); otherwise, I'd have to make the smae update dozens of times if it's documentation on an existing feature .

One other thing to consider: related topics can be in other apps. For example in App 1, a related topic might be something in App 2.

Any pointers greatfully appreciated

Regards

Mark

[Jeff_Coatsworth]

Hmm, lot of requirements here - first off, if you're going to produce printed docs (PDFs), you won't be able to do it directly from RH - it has to go back through Word to get into PDF (that's why I use the Tech Comm. Suite for my docs in FM). You can't do commenting in WebHelp unless you build some sort of e-mail feedback into each topic (probably using the footer of a master page).

You don't talk about how you deliver help & what sort of context sensitive help you want (if any). Is it locally installed, on a webserver someplace, etc.? Most development in software versions doesn't maintain multiple versions - especially in an agile environment; the latest version is the one that gets all the attention. Maybe your shop is different; my company has only 3 supported versions out at any one time & I only maintain the help, on an ongoing basis, for the latest one. Any feedback I get goes into the latest version, not the version that was commented upon.

You can certainly use conditional build tags to "version" topics and parts of topics, but that can get quite messy over time. My preference would be to maintain separate projects for each major release and CBT for the subversions.

If your help is going to be locally installed, have a look at AIRHelp - it's got something called content categories that allows multiple versions to be packaged into one help file & the user gets to choose which to look at. It also supports commenting.

[mark_anderson_us]

Thanks Jeff

Regarding printing, yes, well go back through word. I looked at RH a few years ago and from what I recall, it worked Ok exporting to word (and making PDF from there). Getting everyone to use FrameMaker is too much of a leap and investment. (There are about 12 SME's who create documentation - no dedicated resource)

My preference is to use RH Server, but that decision has not been made, but with the single source layouts, I can begin the proof of concept.

Regards

Mark

[SealedEnvelope]

Is there a way to setup the documentation such that I can flag parts of it to specific versions

Consider avoiding doing so.  You basically have two choices.  One, inclusive document, that has a history of all the changes, with "flags".  Or, multiple documents, each one a snapshot at a given time.  The first can get complex (especially when something goes wrong and it has to be 'restored' or 'recreated'), perhaps even if it is just between major releases.  The second is far less complex, just laborous record-keeping (of document histories, i.e. one full-help doc for each version).  Also, the versioning of new features is sometimes "this/that", one or the other, not have-it-or-don't.  RoboHelp's conditional tags are "this,and".  That is, you can generate a base document, plus some number of tagged or conditioned (excluded) topics.  It's suitable most efficiently if a feature and corresponding text is added, but not so much if something else (and some other text) is replaced by it (you'd have to create another tag for the replaced text).

Generally put, the conditional tags are conditional build tags.  What you describe is more like conditional access, i.e. access only the correct version.  That conditional access could be handled locally, via deployment strategy, by making sure they get the right version help when the version upgrade is installed, or by "conditioning" the help request to the centralized server by providing the version number of the software making the request, so the server can fetch the right document from the help library.

In days past, we used to keep one Word master document, that linked-in what would be your 17 chapters (and sub chapters) of help.  At each version, even smallish, we'd save it with the version number and break the links. 

Right now, I'm exploring whether I can do the same/similar with RoboH, using it as a wrapper, like a master document. 

So far, it's not going exceptionally well, just average.  😞 

You have to do a CSS mapping, that can be time intensive and a "pain to maintain", but no way around it really.  Bulleted lists in Word do not come out as HTML list tags (that might be a show stopper).  There are problems with special character file names.  I'm having trouble keeping a link dynamic AND applying a Robo master-page.  Last, linking/importing is not preserving the Word document's author meta-data.  But, that's just a nice-to-have, because you'd want e-mails (or other reports), to get segregated on return, etc.  In all fairness to Adobe, though, MS Expressions does not allow linking of MS Word documents or even importing of them.  ( ! )

[kmaddox1]

What you describe is similar to what we are doing currently, with a few notable exceptions. Two of us maintain a large number of online user's guides that are published both as Webhelp (25 projects merged into one parent help system) and as standalone .docx and .pdf files. We are also using Agile. Our company offers two or three major releases per year (2011.1, 2011.2, 2011.3) with one or two patch releases for each major release (2011.1.1, 2011.1.2, etc).

Our customers also use different versions--some are still on last year's release (possibly earlier), while others install the latest version as soon as it's available.

A few things you may want to consider:

1. We've had limited success importing Word documents directly into Robohelp--the HTML invariably gets screwed up with a bunch of extra codes from Microsoft. We've found we have better control over the help files if we simply copy the Word text to Notepad and then copy and paste the stripped-down text to Robohelp, where we create topics, apply styles, insert hyperlink, and import images. This method of converting text from Word to RH takes longer initially, but seems to work better in the longer term, especially if the original document had nested lists or complex tables. FWIW, doing the conversion is relatively mindless work--the kind of task that is great to do at the end of a long week when your mind is numb from writing.

2. The start pages for each of our 25 projects are linked to their corresponding modules in the software (users can click the Help icon or press F1 to see the online help for the module or to access the entire help system). However, we do not offer true context-sensitive help.

3. We use the same source control system that is used by our software developers and check our Robohelp files into the same mainline code branch--this means that up-to-date documentation accompanies each release from mainline. Typically, we do not update the help files in our patch branches, since this would mean duplicate work (after updating the help in the patch branch, we'd have to make the same updates to the mainline branch). Instead, we use release notes to document any user interface or functional changes in patch releases. That said, the majority of our patch branches are for bug fixes, not enhancements, so they require only limited changes to the help.

4. Our entire help system is automatically generated during our nightly software build using the RHCL batch command. When customers install a new release of our software, the latest help files are automatically written to their computers.

5. After major releases only, we generate a revised Word/PDF file for each project and post those files on our customer support portal. Other than that, we make no attempt to provide improved documentation to customers who are using downlevel software. That is, if we need to rewrite the basic instructions for some task, we update the mainline branch for use with the next software release and all subsequent releases. I guess we figure that if our customers are interested in the latest and greatest instructions, they should spring for the cost of a software upgrade.

[mark_anderson_us]

Thanks a lot guys

Sounds like kmaddox1's solution is the way to go

[kmaddox1]

Happy to have helped. One other thing: You listed this as a requirement: "related topics can be in other apps. For example in App 1, a related topic might be something in App 2."

By setting up a merged help system, you can easily create hyperlinks that go between topics in the individual projects. We do this all the time. While the initial learning curve for setting up merged Webhelp is reasonably steep, it works like a charm once it's all set up. Peter Grainge has excellent instructions on his web site.

[mark_anderson_us · Accepted solution]

thanks a lot

figured I was going to have ot use merged help. Didin't realize it was a steep learning curve though. Clearly, lots to learn 🙂