organizing help for large s/w product

Forum|Forum|18 years ago
November 14, 2007
3 replies
504 views

You folks have provided some great insights in the past, so I thought I'd canvass you on this question. I'm looking for recommended approaches for setting up what will become a very large help system. I am using RH6 for HTML (soon to be RH7) to create Webhelp and PDFs. My company's very complex software is set up as a number of modules. For example, there's a customer management module, a retail module, an accounts receivable module, a sales and orders module, a reports module, and an administration module--just to name a few.

Since customers have asked for individual user's guides (PDF) for each module, I started down the path of creating a number of individual help projects (one for each module), all using the same topic template. I've been planning to use Robohelp's Merged Project tool to create a master TOC. But as I become more familiar how our software works, I'm realizing that it would be very handy if I could include hyperlinks between the discrete help systems (for example, linking from the help from the customer management module to the related help for the administration module). Is there a way to link from one help project to another (all will be installed locally on the customer's PC)? Or would I have been better off creating one gi-normous help system for the entire software product and setting up conditions to control the printing of individual "user's guides"?

I currently have created help for 3 of the 20+ modules and must have close to 600 pages of printed documentation (including numerous screen shots and graphics) already. Based on that, I'll easily end up with 1000s of pages when I'm done (and an equal number of topics). Is there a practical limit to how big a single or merged help project can be? How many discrete help systems can you merge into one master project? And assuming they let me hire another writer someday, what's the best way to set up this kind of effort to support multiple writers?

Any insights or words of wisdoms you have will be greatly appreciated!

This topic has been closed for replies.

M

MeWrite

Known Participant

quote:

Originally posted by: Kathy Maddox
And assuming they let me hire another writer someday, what's the best way to set up this kind of effort to support multiple writers?

Any insights or words of wisdoms you have will be greatly appreciated!

Actually, if you have a server, RH7 HTML comes with RoboSource which allows you to do simultaneous editing. If you disable this feature, you can still work on the same project by checking out just the topics you want to work on and then the other writer would check out other topics to work on.

Cindy

M

MeWrite

Known Participant

Kathy,

I have a similar situation with one of my clients. Their HR and Payroll modules are so big in of themselves, I found it better to create a new project for each module. I have about 10 modules and the call center likes printed doc for the most part. So here's what I did.

I created 1 project per module (duplicating the templates, css, etc) so that all the projects look the same. I then link applicable items from 1 project to another using hyperlinks then merged all the projects to a master project and it looks seemless to the end user. I created a TOC of all the PDFs for the end user to print what they wanted in paper and sometimes included the PDF as a link on the topic. I posted all these projects on a server designated by their IT department. I have never heard any issues about doing it this way.

I like this option also because it keeps the projects kind of small, thereby speeding up the end users output.

Hope this helps. If you want more specific, just let me know.

Cindy

K

kmaddox1Author

Inspiring

Hi Peter and Cindy,

Wow. Thanks for your very fast and very informative replies. Sounds like I'll be okay with my approach of having one project/module and combining things at the master project level. I do use source control software (just not Robosource) so it's good to know that I can use it to manage a multi-writer, multi-project help system. As for the specifics of actually pulling things together, I'll just bookmark Peter's amazing site and refer to it as I go. But, Cindy, I was curous about your comment about PDFs. Do you include the PDFs as part of the help system that goes to the end user customer? What's the process for doing that? Right now, I create PDFs but they are only available from our Tech Support web site--we don't automatically distribute them to the customers.

M

MeWrite

Known Participant

Kathy,

If you want to include PDFs as an output that goes to the end user, just include them in your baggage folder and everything will ship together after you complie. I just started using RH7, but I would hope that they have not changed this functionality.

If you don't send the PDFs to the client, that's ok, so long as you can hyperlink to where the PDFs are (just include the whole path back to the tech support server). I have done this in the past with other clients, but my current client (a couple of years ago) migrated all my online help and documentation to the same servers so that all my projects, doc, powerpoint, and pdfs sit on the same internal server. So for this company there is no issue of linking to an outside source/server. The only issues I have is when they move or retire a server. Then I just simply republish all the projects again to the new server. Since the PDFs are part of the baggage folder everything remains intack.

Here is another great resource I've been using for years: http://www.robowizard.com/RoboWizard/NewProject.htm. Rick is very knowledgeable, I use his site a lot. He's got great Tips and Tricks. I should warn you though that his site is a bit different. Hope your into "Wizards". ;-)

Cindy

Peter Grainge

Community Expert

I suggest you take a look at the topic on my site about merged webhelp as it will cover many of the questions.

You can create cross project links but remember they will break if they point to a child project that you don't deliver to a specific customer.

The limit to each project size is a practical one. There is no fixed number of pages or graphics. You get to point where you realise the project is taking a long time to open and is straining a bit. In my case that comes in around 4,000 to 5,000 topics in an individual project.

On multiple writers, on day 1 you both have a copy of the whole setup. You agree who works on what project and you never touch the other persons projects. Come generation time, you overwrite the projects in your setup that have been worked on by the other person.

Use the menu (bottom right) to mark the Best Answer or Highlight particularly useful replies. Found the answer elsewhere? Share it here.

Sign up

To post, reply, or follow discussions, please sign in with your Adobe ID.

Sign in to Adobe Community

To post, reply, or follow discussions, please sign in with your Adobe ID.

Scanning file for viruses.

This file cannot be downloaded