Word alternatives for writing user manuals with lots of shared content?
July 11, 2013 1:01 PM Subscribe
I have two user manuals, for two version of a product, which are 75% identical. They're currently Word documents. It's a pain to keep the parts in sync that I need to keep in sync. How can I do this the best way?
Solutions I've tried and rejected involving Word:
* using master/subdocuments - because it seems you're really not supposed to use the same subdocument in two different master documents, so references to numbered headings and figures (and the numbering OF headings and figures) get messed up.
* using included-documents (for the same reason)
I'd LOVE to use something like reStructuredText, but the manual needs to be editable by non-technical users (clinical staff, etc.) as well as by me, so it's just not really an option. Things like Docbook are out for the same reason.
I tried using MediaWiki+VisualEditor, but that doesn't really support the concept of a single long document with continuously numbered headings, which we really need in order to help people find things in the printed version and provide obvious cues as to section structure.
Any suggestions?
Solutions I've tried and rejected involving Word:
* using master/subdocuments - because it seems you're really not supposed to use the same subdocument in two different master documents, so references to numbered headings and figures (and the numbering OF headings and figures) get messed up.
* using included-documents (for the same reason)
I'd LOVE to use something like reStructuredText, but the manual needs to be editable by non-technical users (clinical staff, etc.) as well as by me, so it's just not really an option. Things like Docbook are out for the same reason.
I tried using MediaWiki+VisualEditor, but that doesn't really support the concept of a single long document with continuously numbered headings, which we really need in order to help people find things in the printed version and provide obvious cues as to section structure.
Any suggestions?
Depending on the 25% of each that is different, can you have one master manual for both products and use an appendix or supplement for the parts that are different? You could insert links in the word document to a separate document file. Use different colored text for each product link to aid people in choosing the right link when jumping to the appendix.
posted by trivia genius at 1:21 PM on July 11, 2013
posted by trivia genius at 1:21 PM on July 11, 2013
I'd use the Master doc method in Word, which incorporates subdocuments. It's completely invisible to the document reader, except that all docs have to be present in the same folder of course - but I assume you convert to PDF for publishing.
The catch is that you really can't insert less than a paragraph of material, so it's not good for merge operations ("The power output is 21/32 Watts.")
When updating, it's best to work in Master document view, so you can see the document end limits.
posted by IAmBroom at 1:27 PM on July 11, 2013
The catch is that you really can't insert less than a paragraph of material, so it's not good for merge operations ("The power output is 21/32 Watts.")
When updating, it's best to work in Master document view, so you can see the document end limits.
posted by IAmBroom at 1:27 PM on July 11, 2013
Scrivener? It has a master document / subdocuments structure.
posted by mattbucher at 1:36 PM on July 11, 2013
posted by mattbucher at 1:36 PM on July 11, 2013
The term you're looking for here is "single sourcing", and there's a whole ecosystem of arcane technical writing tools that have grown up around exactly the need you've described (there's a list in that first linked article). One big player in that scene is Adobe's Technical Communications Suite, which includes something called RoboHelp: a "multichannel publishing solution".
Other popular tools in the same vein are MadCap Flare, Author-it, and ComponentOne's Doc-to-Help. There are also wiki-based solutions in this space, e.g. MindTouch, which sacrifice power for ease-of-use and might be better for the non-technical users you mentioned.
(Full disclosure: I used to work for a RoboHelp competitor.)
posted by The Minotaur at 3:52 PM on July 11, 2013
Other popular tools in the same vein are MadCap Flare, Author-it, and ComponentOne's Doc-to-Help. There are also wiki-based solutions in this space, e.g. MindTouch, which sacrifice power for ease-of-use and might be better for the non-technical users you mentioned.
(Full disclosure: I used to work for a RoboHelp competitor.)
posted by The Minotaur at 3:52 PM on July 11, 2013
Best answer: You don't want RoboHelp, because that primarily creates online help systems. Ditto for Flare, etc. Single-sourcing means creating multiple outputs from one set of files. Usually, creating a help system and a user guide. This is costly, and does not support what you are doing. MindTouch is a great wiki tool, but it also does not do what you want to do.
What you really want, and what tech writers have been using since the late 1990s to meet exactly the need you currently have is Adobe FrameMaker. The task you are trying to accomplish is called "conditional text."
Let me give you an example: You are writing a manual for a car. The car comes with the regular package or with an upgrade package. The upgrade is the same except it has leather seats and the radio includes a CD player. You write one book. In the chapter about the radio, you write about the CD player and mark that text as conditional -- it has the condition of being in the upgrade's book. Similarly, maybe there is some text that is only true for the regular package -- you can mark that as conditional, too. You might later go and tag all the references to the year, and make that a condition also or mark so that you can update the product year in one place, and it makes that change globally.
With Word, you can kinda have one condition, in that you can mark text to disappear. But that's just one condition. Master documents has been broken in Word for more than a decade. With FrameMaker, you can have as many conditions as you want, the conditions can be entire chapters or as small as a single letter, and in the end it'll still support your cross-references, table of contents, index, etc., and that's the primary reason tech writers use it.
I've been professionally using all the tools I mention for about 15 years now.
posted by Houstonian at 6:24 PM on July 11, 2013 [1 favorite]
What you really want, and what tech writers have been using since the late 1990s to meet exactly the need you currently have is Adobe FrameMaker. The task you are trying to accomplish is called "conditional text."
Let me give you an example: You are writing a manual for a car. The car comes with the regular package or with an upgrade package. The upgrade is the same except it has leather seats and the radio includes a CD player. You write one book. In the chapter about the radio, you write about the CD player and mark that text as conditional -- it has the condition of being in the upgrade's book. Similarly, maybe there is some text that is only true for the regular package -- you can mark that as conditional, too. You might later go and tag all the references to the year, and make that a condition also or mark so that you can update the product year in one place, and it makes that change globally.
With Word, you can kinda have one condition, in that you can mark text to disappear. But that's just one condition. Master documents has been broken in Word for more than a decade. With FrameMaker, you can have as many conditions as you want, the conditions can be entire chapters or as small as a single letter, and in the end it'll still support your cross-references, table of contents, index, etc., and that's the primary reason tech writers use it.
I've been professionally using all the tools I mention for about 15 years now.
posted by Houstonian at 6:24 PM on July 11, 2013 [1 favorite]
Response by poster: Houstonian, can you tell me more about the conditional stuff in Word? I couldn't find any such feature that wasn't tied up in the Mail Merge stuff.
posted by dmd at 6:50 PM on July 11, 2013
posted by dmd at 6:50 PM on July 11, 2013
Best answer: Yes. They don't market it as such (conditional text), but it can be used that way. It's the hidden text feature. In Word 2012:
1. Highlight the words you want to hide.
2. On the Home tab, in the Font group, click the launcher to open the Font window.
3. Select Hidden and then click OK.
That hides the text. Now, if you want to see what text is hidden (in that it displays on screen but not when you print):
1. On the File tab, click Options.
2. In the Display section, under Always show these formatting marks on the screen, select Hidden text and then click OK.
That's the basic idea. To get fancier, you could create styles for hidden text and use those. Then, create a macro that swaps the hidden style with the unhidden one.
In the example I gave earlier about the car, you have the regular package and the upgrade package. Let's say your book has only two different font usages -- one for a heading, and one for text. So, you create four styles:
- Heading: This is Arial 16 point.
- HeadingHidden: This is Arial 16 point and hidden.
- Body: This is Arial 10 point.
- BodyHidden: This is Arial 10 point and hidden.
Your chapter for the radio would use HeadingHidden and BodyHidden for the parts about CD player. Keep that hidden, and you have the book for the regular package. Unhide it, and you have the book for the upgrade package.
But you see that presents a problem. Let's look now at the section for maintaining the seat covers. The regular package comes with cloth seats, and the upgrade has leather. If you hide the leather, you have the cloth -- that's ok. But if you expose the leather section, there's no hiding the cloth section -- and that's not ok for the upgrade's book. That's because you have only one condition: Show/hide only one type of thing.
I suppose you could then create multiple styles, and swap them out with a macro, like this:
- Heading
- HeadingHiddenInUpgrade
- HeadingHiddenInRegular
- Body
- BodyHiddenInUpgrade
- BodyHiddenInRegular
But then, they all look the same on your display, so it's very confusing. You could then assign them different colors and have those also change with a macro back to what it's supposed to be, but seriously by then you really should have purchased FrameMaker.
posted by Houstonian at 11:09 AM on July 12, 2013
1. Highlight the words you want to hide.
2. On the Home tab, in the Font group, click the launcher to open the Font window.
3. Select Hidden and then click OK.
That hides the text. Now, if you want to see what text is hidden (in that it displays on screen but not when you print):
1. On the File tab, click Options.
2. In the Display section, under Always show these formatting marks on the screen, select Hidden text and then click OK.
That's the basic idea. To get fancier, you could create styles for hidden text and use those. Then, create a macro that swaps the hidden style with the unhidden one.
In the example I gave earlier about the car, you have the regular package and the upgrade package. Let's say your book has only two different font usages -- one for a heading, and one for text. So, you create four styles:
- Heading: This is Arial 16 point.
- HeadingHidden: This is Arial 16 point and hidden.
- Body: This is Arial 10 point.
- BodyHidden: This is Arial 10 point and hidden.
Your chapter for the radio would use HeadingHidden and BodyHidden for the parts about CD player. Keep that hidden, and you have the book for the regular package. Unhide it, and you have the book for the upgrade package.
But you see that presents a problem. Let's look now at the section for maintaining the seat covers. The regular package comes with cloth seats, and the upgrade has leather. If you hide the leather, you have the cloth -- that's ok. But if you expose the leather section, there's no hiding the cloth section -- and that's not ok for the upgrade's book. That's because you have only one condition: Show/hide only one type of thing.
I suppose you could then create multiple styles, and swap them out with a macro, like this:
- Heading
- HeadingHiddenInUpgrade
- HeadingHiddenInRegular
- Body
- BodyHiddenInUpgrade
- BodyHiddenInRegular
But then, they all look the same on your display, so it's very confusing. You could then assign them different colors and have those also change with a macro back to what it's supposed to be, but seriously by then you really should have purchased FrameMaker.
posted by Houstonian at 11:09 AM on July 12, 2013
« Older Finding local employment in Toronto - websites... | Background music for these experiments was... Newer »
This thread is closed to new comments.
posted by RonButNotStupid at 1:18 PM on July 11, 2013