Skip to main content
DLindsay
DLindsay
Inspiring
October 31, 2018
Question

Advice on most efficient approach

  • October 31, 2018
  • 1 reply
  • 389 views

I have a dream re-use scenario to work with at the moment. I can see several ways to approach it, and wanted to check in with anyone who's done this before for advice.

I am putting together a user guide and release notes for an adapter product. The product connects system A, B, or C to system 1, 2, 3, or 4. A customer only needs info the systems they are connecting between. This results in 12 user guides and 12 release notes (for system A-1, A-2... ...C-3, C-4)

Current approach:

The content has been created as DITA concepts, tasks, and references, and with separate versions of each DITA file for each relevant system. Common content is reused via conrefs to shared files.

12 ditamaps connect these files as needed to create each variation of the user guide.

This works, but I don't want to have to go through the publish process manually 12 times each time we do a software update. The process involves:

- Open ditamap

- Generate composite book with components

- Add in an fm file for revision history

- Import variables to all files in the book to update version number, release date etc

- Regenerate page numbers & TOC (they changed because of inserting the revision history table)

- Save as PDF and check everything is fine.

How much of this can I automate with a script?

Or, is it better to use 1 ditamap and combine my dita topics so they contain info for all relevant system types identified by (e.g.) the product parameter and use a ditaval on publish to generate whatever variation is needed? Would this be easier to automate despite the greater complexity in the source files?

Thanks in advance!

Kat

This topic has been closed for replies.

1 reply

R
Russ Ward
Legend
November 1, 2018

Hi Kat,

Is there a reason that you are using DITA at all? From your description, DITA seems like it might be the wrong toolset. This sounds like a job for the conditional text model, rather than a modular topic-reuse approach. DITA is very good at the latter, but I rarely see a use case for it.

With DITA, you have to break your content in pieces, then spend time putting it all back together again (ie, the map). If you are not reusing topics in broadly different contextual areas, this is an exercise just for the fun of it. Plus, it reduces the effectiveness of the author, as it removes the context between topics that helps us keep things straight.

If I had 12 different final publications to produce and they all followed the same contextual order, I would much rather create a composite guide, then run conditional text filters on it to produce the 12 outputs. With that, I would much rather just tag a chapter in an FM book for system A-1, rather than break everything into pieces, just to reassemble them into a map for document A-1. The first approach is significantly less complex. Furthermore, the second approach does not gain you anything, unless you have a need to reuse the topics elsewhere.

To be clear, I am not talking about the native unstructured conditional text model, which is obsolete and generally unmanageable for any serious application. I'm talking about conditional tagging with structural metadata, such as attribute values. I have been using the structured conditional text model for a long time and find it normally more effective than the topic reuse approach. Unfortunately, out of the box, FrameMaker has pitifully weak features with respect to this model, so weak in fact that I regard them unfit for any serious usage. So, I wrote and use the AXCM plugin to fill in that gap, which is free now and forever:

AXCM Plugin - West Street Consulting

So, I don't mean to disrupt your plans too much here, because I am suggesting a significant rethink. It might be worth it, though. Somehow, it seems that people drift into DITA without a full, objective analysis, then end up with a workflow that adds more burden and complexity than necessary, while reducing the ability to reach the end goal. It certainly is a very clever concept and has its place, but there are many places where it is the proverbial sledgehammer to drive a nail. DITA does have conditional text mechanisms too, but you'll need to swing the sledgehammer first just to use them.

Russ

DLindsay
DLindsayAuthor
Inspiring
November 5, 2018

Hey Russ,

Thanks for the detailed answer. We use DITA because it's the company standard and in general it's easy to work with. It keeps our topics written fairly consistently and we do find ourselves dropping content in and out often enough to appreciate the modularity. I don't find it particularly onerous to work with multiple files as I can open whatever I need from the ditamap. And all our writers know how to work with DITA now. The docs aren't particularly long.

But as you mention, it's possible to do the conditional approach you describe with DITA too - setting parameters to A, B, C, 1, 2, 3, 4 and then using the DITAVAL file. I did some experimenting and was able to get this to work. I'm just unsure whether it's easier to maintain one ditamap plus making sure all the sections have the right parameters assigned and then having to apply the ditaval file during publish, or whether my current approach is best. I think it'll come down to how much of the output process can be automated.
Happy Monday!
Kat

Terms & ConditionsAccessibility statement
Using the community Terms of use Privacy Cookie preferences Do not sell or share my personal information ad choicesAdChoices