Slashdot Mirror
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!"
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!"
From what you've described, all the manuals would have to be re-formatted to be in this new web format. Depending on the complexity of the manuals (100 pages of flat text vs. diagrams, charts, pictures, etc.), this is probably a job for a Technical Writer, not for the person designing the documentation system. Given that there's little to no budget, I think it's perfectly accurate to tell your boss that it can't be done.
I would recommend this: Transfer the print versions of the manuals to PDF, like you originally suggested. Try to convince your boss to try this, and see how your customers like it. Since PDFing the print manuals is same thing that everyone else does, your customers will be expecting it and will already be used to it. (Play up the "no user training" angle.)
Speaking as someone who has had to look up manuals for all sorts of odd standards and parts online, I always find a PDF to be the best thing: You can save a PDF to your hard drive. When printed, it always looks the same, no weird printing anomalies. You can bookmark a PDF's online location very easily. All of these things may or may not be true of a "Yahoo-like interface with categories".
And one other thing: That "Show printable version" thing that you'd still have to have with the Yahoo-like interface: Most likely, that would be the PDF that you want to generate in the first place!
If you can't convince your boss to go for just the PDFs, try to convince him of a phased deployment: put the PDFs online now, because they're basically already done. THEN start on designing whatever fancy system they're looking for. Eventually, there will be a time to choose "what we have now, for free, vs. this fancy thing, for $$$". Hopefully, they'll choose what they already have.
Your big problem is convincing your management that you're not just indulging in simple foot dragging. So you need evidence that's harder to argue with than anything you have. Like metrics.
Consider some kind of pilot project. Pick a manual, make a plan for converting it into a set of those "Yahoo-like" web pages they're in love with. The real-world cost of doing that will put the whole plan in perspective.
The big question is, what kind of budget do you submit for the pilot project. If it's too realistic, management might think you're dragging your feet by inflating costs. You can loball in order to cater to management expectations, but that guarantees that the pilot project will fail. Of course, that failure is itself very instructive...