Linking Word documents - pros/cons/gotchas

Hi,

I've been using this workflow for over a year. My main project is a disaster recovery manual. The teams I work with all have their own documentation, but it was scattered on Wikis and in many different folders on many different network drives. One of the project's goals is to consolidate all those different places into a single place. Thus, I work with the teams to move their documentation to a centralized folder structure. Since I began working on this project, I have posted many times about this exact functionality within RoboHelp on my blog -  prhmusic [dot] blogspot [dot] com - and used the label "RoboHelp" for the relevant posts, though not even close to the amount of information about RoboHelp that you would find on Peter's site or Rick Stone's site or Willam's site.

What things do I need to watch out for?

1. Make sure your Word documents that you are linking to are going to stay in the same place and not move around because otherwise you will have to re-link the Word documents. I wrote about it in a blog post called "How to change the Default Folder."
2. Make sure you are more rigid in applying styles than you can imagine yourself being. Create a template for the Word docs and define styles. I use AHCIS[P or C][Description]. The [P or C] is used to define whether the style is a character style or a paragraph style

   .

3. I'm glad you've found Peter Grainge's website. It is an excellent way to get your feet wet.
4. Establish a folder structure within your Project Manager in RoboHelp so that you can drag a level-1 folder to the TOC pane and have the TOC automatically create itself.
5. In my situation, the SMEs have Excel, PDF, Visio, CSV, and other file types in their folder. These files do not have the same ability in RoboHelp where you will know one or many of them have been updated. You will have to add them as Baggage Files. Peter & Rick have a lot of great content about Baggage Files on their sites. I am old school, meaning I like MS-DOS. I have a batch file that copies all of those file types to my local c:\rh\drm folder so that when I publish, I have the most up-to-date files. There's no icon to tell you that ABC.PDF has been updated in the s:\dir1\dir2\dir3 folder and if you have 300 PDFs, you're not going to go check each of them. There are freeware tools that will tell you if there is a change to a file in a watched folder - I can send you a recommendation if you need it.
6. To RoboHelp, the HTML files it generates from a Word doc and the HTML file that you author with HTML code are the same. That means, there's no report or way to generate a list of topics that are for the linked Word documents. You can tell if you look at the Topic list. The HTML files that RoboHelp generates will always have more than one CSS file. What I do is make the HTML files I code directly in HTML have a single CSS file. Below is a snippet of my topic list. The topics inside the green box are ones that RoboHelp generated; whereas the ones with PRH_HCIS_DRM.css are ones that I created directly with HTML code (they don't have a Word document associated with them:

What can go terribly wrong?

When Peter wrote this above:

|

Documents that have been around many people and picked up unused styles is a good one. Hence using a macro to clean imported documents. The problem is you can't do that with linked documents. If you can get those documents clean and not edited by too many people, it helps. Generally once you have mapped the styles first time, updating shouldn't be too painful.

|

I had a different thought. You can run a macro to clean up the styles in your linked document. The trick is that you have to have access to the Word document in the network folder (or wherever it's stored) and the authority to do style changes. What I do is assign a series of templates that include one that has the macro I use to remove unused styles. I know there are things you can do to 'lock down' a Word document and only have a specified set of styles available to the SME, but I haven't done more than research that option. I interpret what Peter wrote above to mean that you need to have a clean Word document, with styles properly applied, to get a clean output in the HTML file(s) that RoboHelp generates because cleaning up the HTML file(s) that RoboHelp generates will take you directly to The Hamster Wheel of Frustration, which is described below - stay tuned!

Here's some other thoughts about what can go terribly wrong:

1. The Word documents are renamed by the SMEs. After that happened, I added a note in the header of the Word doc that says, more or less, 'this document is linked to a RoboHelp project and should not be renamed. If you think it should, please email me' and then my email address.
2. There's another thread about .FPJ files. Here's my thought about them - DO NOT EDIT THEM!! You may think you know what you are doing but I have had nothing but agony when I tried to 'fix' something using Noepad and what I thought was a clever idea. LEAVE THEM ALONE!!
3. My experience and what works for me is to generate the HTML file(s) through RoboHelp immediately after I link a Word doc. In my experience, not doing so can be bad. I use a lot of folders in my Project Manager. One time, I linked Word docs in different folders and had the folder disappear in Project Manager . . . until I generated the HTML file(s). My theory is that happened because there was no information to be written to the .FPJ file. That's why I do it.

What workflow do you use? e.g. SMEs write and update the docs, you edit then update and publish in Robohelp.

Yes. The documents are stored on the network in a specific folder structure that the SMEs update / maintain. When there is a change, the icon in RoboHelp changes to yellow so I know I need to regenerate the content.

There is another consideration, from a technical writing standpoint that you also have to consider. If you have many SMEs writing many different documents, you will have many different writing styles. You may have Jim who loves to write "Click the Add button." and then have Sue who loves to write "Click Add." In the context of a single output, you will want to have a unified voice & a unified way of writing the same content. You do this because you don't want the reader to be able to tell that different people wrote the documentation they are reading. Also, if Jim loves the word "modified" and Sue uses the word "changed" and they mean the same thing, you're asking the user to question why two different words are being used to describe the same thing and if there is a difference. That may be an oversimplification of why a style guide is necessary, but I hope it drives home the point that just because the SME is writing the content, you, as a technical writer, still need to review and, in some cases, make editorial changes in the name of consistency. This is the other 1/2 of why you use specific styles in your Word docs - so that the generated HTML files look consistent. If they look consistent but are not written in consistent style, to me, you are only 1/2 way there of delivering a professional output.

You write the docs in word, SMEs review, then you update and publish in Robohelp? Something else?

See above.

What works well?

What works well is having a conversation with the SMEs prior to linking. Give them the big picture as to how their content will mesh with the other content you are linking to as well as to any content you are writing.

What features of Robohelp are unavailable using this method? I assume dropdowns won't be possible.

Well, you could add drop-downs to the HTML files that are created automatically by RoboHelp . . . . if you want to be on The Hamster Wheel of Frustration!! What would happen is RH would generate the HTML file, you'd change it, and then RoboHelp would say the HTML file has been updated, and want you to regenerate it. However, when you regenerate it, your changes will be wiped out. So, no, you can't really use drop-downs.

• Peter mentioned drop-downs as it relates to printed doc. I developed a strategy for how I could use drop-downs in my browser-based output and to just display the text that shows up in the drop-down in a Printed Documentation output. I won't cloud this post with that strategy but if it is something you want to know more about, let me know.

Another thing I never thought about is linking. I had a hyperlink to a PDF in one of the linked Word documents and RoboHelp changes all the links to be direct... that's not the right word... the opposite of a relative link. Like if you have a link in a Word doc to open "ABC.pdf" that sits in the same s:\ drive folder as the Word doc, RoboHelp will change it to s:\dir1\dir2, etc during the compilation process. What I do as a workaround is to create a separate HTML file with hyperlinks to the relevant PDF files (as I mentioned above) and then include that page in the TOC. I use a naming convention. In the title, all of those pages begin with "External Resource" so that I can sort by title and have them grouped together. Recently, after I began to create a bunch of these pages, I went back and created a snippet that has my standard blurb:

|

|

So, if you are going to have to link to many non-Word files, create a snippet so that your text is the same for each of those pages.

What about having a single topic appearing in multiple places in the TOC?

That shouldn't be an issue - you can do that. What you won't be able to do is have the browse sequence work the way you might expect. I wrote about that on another thread in the forums within the last year that I can try to find if you need it.

Is anyone using this in a merged Multiscreen HTML5 output? Linking from content in the linked word document to a topic in one of the other child projects?

What if only one project is using the linking feature and all the other projects are being managed in Robohelp?

I am not working with merged projects - I have some other projects using this functionality but they are not merged to look like a single help system.

I can answer some of your questions.

What things do I need to watch out for?

I'll leave others to expand on this one but mostly what I have written is based on what I have seen go wrong for myself and others.

What can go terribly wrong?

Documents that have been around many people and picked up unused styles is a good one. Hence using a macro to clean imported documents. The problem is you can't do that with linked documents. If you can get those documents clean and not edited by too many people, it helps. Generally once you have mapped the styles first time, updating shouldn't be too painful.

What workflow do you use? e.g. SMEs write and update the docs, you edit then update and publish in Robohelp. You write the docs in word, SMEs review, then you update and publish in Robohelp? Something else?

Again you need others to expand on this one. My own method was to create in RoboHelp and then produce a printed document from that.

What works well?

I'll leave others to answer this one.

What features of Robohelp are unavailable using this method? I assume dropdowns won't be possible.

From Word to RoboHelp - How are you getting dropdowns working in Word?

From RoboHelp to Word - The printed document can include the content of a dropdown but not as a dropdown. My solution was to specify dropdown content in a different style. Indenting can help.

What about having a single topic appearing in multiple places in the TOC?

The link gets updated when you generate. After the topics have been created I see no reason you cannot have those topics in more than one place. Trial and error on this one.

Is anyone using this in a merged Multiscreen HTML5 output? Linking from content in the linked word document to a topic in one of the other child projects?

Links within the same Word document are OK. Links to web pages are OK. The only way I can see this being done to another child project is if the link points to the address of the child project where it is generated. Again, trial and error.

What if only one project is using the linking feature and all the other projects are being managed in Robohelp?

The one using linking is also being managed by RoboHelp so I am not sure what you see as the problem here. It should not matter that only one or some of the child projects have linked documents.

****************************************

If you are considering writing in RoboHelp and giving a Word document to SMEs, a method I used was a combination of use Word's Compare feature on what I issued and what I got back. Also I asked the SMEs to precede any change with three hash tags. That made searching for the changes easy.

Hope that helps and others will add their experiences.

See www.grainge.org for RoboHelp and Authoring information

@petergrainge