Moving Manuals Online?

m1cajah asks: "I've been trying to find an 'all-in-one' package for creating (and migrating to) online manuals and am having some difficulty finding what I'm looking for. I'm hoping Slashdot can help. We have a large number of manuals (designed for paper-based presentation) that suddenly need to be provided online to our customer base. Yes, the PHBs have changed the landscape on us once again. This will, once configured, be managed totally by the documentation staff and analysts (none very tech-savvy). It needs to be really easy to use because I would like to say there's a huge budget for this (as well as for training), but there isn't. Lower cost is good. Free is better.Can any of you point me to some other options?" "Adobe PDF with a simple HTML index was suggested, is cheap, and is easily workable. Which (of course) immediately made that solution out of the question. LOL!

What we're told to produce is a 'Yahoo-like' interface with categories. Under the each of the categories they want links to the various manuals. Under each of the manuals, they want links to each individual chapter. Each chapter needs to be printable so a 'show printable version' feature would also be nice.

The manuals are just about everything you can think of - engineering specs, user manuals, manual test scripts, etc.

And 'Oh yeah...we want it version controlled also.'

So, I've found RoboHelp (seems to be some predisposed hatred for that tool...I've asked and they really don't like it), Doc-to-Help, and AuthorIT (I've used it in the past and it worked fine until you tried to deviate from the OOBE).

I've suggested some PHP content management servers like Typo3, the various Nukes, etc. No go. I can't implement anything that does not work directly with IIS6 and the .NET framework (don't shoot me...I didn't pick the software!). There would be some vitriolic blowback if we implemented PHP, Perl, and/or Python. Oracle and SQLServer are the only options for the DB backends (if needed...we have both).

Sharepoint Portal Server might be possible (but the PHBs don't like the cost) because the content could be stored and version controlled with WebDAV (or integrated with Visual SourceSafe).

Please help!"

Comments

Wiki!

[nocomment]

We recently migrated our docs to a wiki. It's very nice. Takes a lot of the load off of us as various departments can update their own docs easily when they get the chance.

Re:Wiki!

[willis]

We use wiki at my company, as well -- it works pretty well, but it gets a little duplicative sometimes. It'd probably be worth our effort to have somebody comb through every once in a while to make sure everything is in one place only...

One little detail

[fm6]

You talk about PDF, HTML, CMS, and a lot of other technology for delivering your manuals online. But these are your goals. Before you can consider goals, you have to understand your starting point. In other words -- WHAT FORMATs ARE YOU CURRENTLY USING TO MAINTAIN YOUR MANUALS????? Before you do anything else, go back to your tech writers and ask them that.

In any case, you're certainly going to have to scale back your expectations. It's easy enough to set up an a fancy CMS that will deliver nicely structured web-based manuals. But you've got to get your manuals into the CMS!!!!.

It's a safe bet that your current documentation base is a collection of word processor and graphics files -- Microsoft Word, FrameMaker, Visio, various Adobe formats. Getting these unstructured formats into the sort of simple, clean online CMS your talking about is a big effort. And that conversion has to be done by carbon-based units -- there's simply no technology to do it automatically. (There's various forms of software snakeoil that claims otherwise -- but it's pure bullshit. AI isn't that advanced!) Unless your management is a lot more open to spending money than they appear to be, it's not going to happen.

Which is not to say that you can't convert your documents into web pages. That's actually pretty easy, since all the abovementioned programs have some kind of HTML export. Just one problem: the HTML you create will be at least as messy as the original documents. You can put it online, add a search engine, and have a document base your customers will find very useful. But it'll never be the fancy, clean CMS-driven web site your management is hoping for.

(If most of your documents are in unstructured FrameMaker format, I strongly recommend using the full version of WebWorks Publisher instead of the limited version that ships with FrameMaker. And there's a version for Word that works rather better than Word's own HTML export feature. WWP has nice table-driven transformation macros that eliminate a lot of work and messiness. Not all of it, alas.)

And if none of your tech writers are tech-literate enough for you, you might consider hiring one who is. (I'm available!) Though you should also consider whether there aren't some two-way communications issues with your tech writing team. There usually is.

wiki's, doc generation tools

[Darth_Burrito]

I'm just starting to use dokuwiki at work. It seems reasonably pleasant. However, one problem with a wiki is that it's probably hard to enforce an organizational pattern. With a small amount of documentation that is ok, with a lot of loosely connected information, that's probably ok too, but it's probably not too good when you need a uniform hierarchy. If you are restricted to dotnet and want a wiki, I think flexwiki is dotnet. It's also what MS uses at channel9.

Depending on what kind of documentation you are talking about putting online, you may want to look at ways to generate it as opposed to converting it. In other words, this could be an opportunity to improve your documentation or reduce the costs of generating it. You may want to look into tools like javadoc or doxygen.

Personally, and this is just an opinion, I think that pdfs are a completely inappropriate format for conveying information over the web. There are really only a few reasons to use pdfs on the web:

• You want to save money at the expense of ease of use for customers and you are already invested in pdfs.
• You want to provide a big document that can be downloaded and printed off all at once (I never want this out of online documentation).
• You need to have everything look the same everywhere.

Otherwise, you're better off with online documentation that is written in the language of the web. It's stylistically and semantically consistent. It loads fast. No special software is required. It has the illusion of being more dynamic (read up-to-date) whether or not it actually is.

PHB's strike again.

[ColaMan]

It sounds as if they've no firm idea on what they need.

Personally, I'd tell them that there is no current alternative that will suit all their requirements, and perhaps they should consider the simple PDF/HTML setup as an interim step.
Suggest that perhaps after a 6/12 month bedding-in period, they would then have a good idea of what is needed and then they could head on down the track to something that is suitable for everyone.

Phrase it in lots of PHB-speak though. Something like "aggregate time-based usability heuristic analysis" sounds good. Mention that it would be costly (both in $ and man-hours wasted) to barge off in some direction, any direction, just for the sake of having an online document repository **right now**. Don't be obstructive about it, try and present yourself as the cool head of reason.

Later, in the real world, logs could be analysed as to how people go about accessing the docs.
Eg. Perhaps people would prefer to get the whole manual rather than chapter-by-chapter, especially if your documentation is a little... scattered,with references to other chapters/pages/ etc.

How about Omnipage?

[msoftsucks]

Omnipage by Scansoft allows you to scan in paper docs and convert them to XML/HTML. It's not OSS, but it does work quite effectively.