1 Reply Latest reply on Feb 8, 2008 11:31 PM by Peter Grainge

    RH5 to Sandcastle Migration?


      I have a large outdated Robohelp project that I'm thinking about migrating to Sandcastle to allow doc builds to be dropped right along with the code. Maybe Robohelp X5 can do that, but it's beyond me. Also, I'd like to be able to have the dev's do more editing on their own once my contract is up. If I understand Sandcastle and its plug-ins correctly, a lot of the conceptual / expository stuff (beyond the generated API doc) can be created right in VS from within the build tree.

      Anyway - the biggest problem I see at the moment is getting clean HTML out of RH. What I see in my source has bizarre markup that I've never seen before. What is Kadov anyway?

      So - any suggestions about how to get clean HTML, and any other thoughts about other criteria I need to think about?

        • 1. Re: RH5 to Sandcastle Migration?
          Peter Grainge Adobe Community Professional
          I cannot comment on Sandcastle but I think there are some fundamentals where I can add something.

          First let's address the kadov issue. In RoboHelp 7, kadov has gone. That does not mean the HTML in a source topic is now the same as the HTML in an output topic. The source has to contain information such as build tags so that when you generate your output, RoboHelp knows which topics and which bits of the content to include or exclude. That applies to MadCap's Flare as well and I would assume all the other HATs that offer such functionality. It is not wrong, it is necessary if you want to be able to single source. The oft seen term "clean HTML" ignores the need for source topics to contain code not seen in the output and that applies to other authoring tools as well.

          Now let's turn to developers editing the topics. For a start, I have said before that part of the technical author's role is to translate from developer speak to user speak. What you propose cuts out that translation. I am not having a pop at developers We have some great guys but they are not great at explaining their work in terms the end user understands, by their own admission. Often when we sit down and discuss some point and I then write it up, the response from them is along the lines "yes, that's right and that's much clearer". As well as their ability to write it clearly, you also have to factor in their desire to write it clearly. Generally it is a part of their work they dislike so that shows in the quality.

          Next, how does whatever they write up transition into RoboHelp? I cannot see how that will get down but that is part of your question and maybe someone else can comment. However, let's consider another Adobe tool such as Dreamweaver. The HTML there is the same in the source and output, the file on your PC is identical to the file on the server. That means if you can get your Sandbox stuff into Dreamweaver, it's ready to go. But what is ready to go. There's no TOC, index or search built in. There's no ability to flag a topic or content as not being for a particular build. Who is going to check that the revised content still makes overall sense? If you put in an external search tool, who is going to rerun the search database?

          If you do go down this route, consider those points very carefully. Also bear in mind you have given some of your work away. :-)