Copy link to clipboard
Copied
Hi all,
I'm investigating using the Word document linking feature in Robohelp. I've read Peter Grainge's website about how to do it, but I'd like to get feedback from people using (or who have used) the feature.
What things do I need to watch out for?
What can go terribly wrong?
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?
What works well?
What features of Robohelp are unavailable using this method? I assume dropdowns won't be possible. What about having a single topic appearing in multiple places in the TOC?
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?
(Basically, think of the most complicated scenario possible and give me the bad news. )
Thanks in advance.
Robohelp 11
Merged project setup
Multiscreen html5 output (desktop target only, heavily customised)
Two css files - one for release notes and one for everything else
Word version - unsure - I have 2013, but some of the SMEs may have 2007, some may have newer, depending.
Copy link to clipboard
Copied
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
Copy link to clipboard
Copied
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?
.
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:
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.
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.
Copy link to clipboard
Copied
Thanks guys, these responses are great!
I'm going to print them out and study them. I'll get back to you with any other questions I have.
Copy link to clipboard
Copied
The reason I said you cannot run the macro on a linked document was that you don't own it and it might contain styles not currently in use but that are required. You won't get a nice thank you when the owner goes to use it and finds you have trashed it. Of course, it that is not an issue go ahead.
Re dropdowns, Paul Why you would want just the content of a dropdown in a printed document and not have the link and surrounding text to put it in context? Just curious.
See www.grainge.org for RoboHelp and Authoring information
Copy link to clipboard
Copied
Re: owning linked documents, I don't "own" the content, but I've told the teams I work with, basically, that I reserve the right to make changes to the formatting so that it plays nicely with the Word style --> CSS style 'translation' parameters I've set up - thus far, there's been no push-back on that. Of course, yes, I have to be aware of what any macro I run will do to the Word doc.
And after I reread what I wrote about the drop-downs above, I see I was too cryptic. When I wrote that, I was thinking about how I handled a table of contacts - name, title, email, phone - that needed to be in both the printed output and in the browser-based output, In the browser-based output, I put the table in a drop-down with a "Click here to see contact information..." link under a heading and in the printed doc, I just displayed a heading. The is code from a HTML file that I author directly with HTML - it's not code that RoboHelp generated for a linked document. I added some extra comments to better explain what I did: