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!"
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.
/* oops I accidentally made a comment, sorry */
Start a document management system for your resume.
I keep a Word Doc, PDF, HTML and plain text version. The manual update is a small hassle, and converting a formatted doc to a plain text version is annoying.
Oh, and many places require you to submit a Cover Letter as a Word Doc attachment in your email. I know it sounds lame, but it's helpful to have a word and plain text version of the same text.
94% of Repubs and 21% of Dems voted to renew the Patriot Act
And assign a part-time or full-time person, depending on the total volume, to manage a simple, minimal website.
What I'm listening to now on Pandora...
Make a webpage something like this
I use this site all the time to look up little arcane tidbits of info, and it's really usable.
"If you think you have things under control, you're not going fast enough." --Mario Andretti
Sounds like you should just whip up a web-site with some pdf-files. Not a perfect solution, but certainly the cheapest...
Use Ghostscript and RedMon to creat a virtual PDF printer. http://www.cs.wisc.edu/~ghost/redmon/index.htm
...But I digress. TREMBLE PUNY HUMANS!ONE DAY MY SPECIES WILL DESTROY YOU ALL!
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.
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.
How does your current documentation exist in source form? Do you only have the Hard copy or do you have the source of what they used to build the hard copy? If the source is LaTeX then it shouldn't be hard to convert it to PDF, HTML or whatever darn format you want.
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.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.
You are in a twisty maze of processor lines, all alike.
There is a lot of hype here.
Well, (sigh) sticking by your stated parameters, I'd say Ektron is probably the best product I know of.
http://www.ektron.com/
It's not great, but it's better than a lot of other crappy Windows-Instant-Intranet products, and it costs less than many of them.
Nice place to work, by the way. "We'd like it free, but if you suggest using any of the best tools available for the job, free or otherwise, we're going to give you a faceful of vitriolic blowback, mmmkay? We know what kind of problems these 'free software' products cause with all their stability and interoperability. Just asking for trouble if you start messing around with that stuff. Hey, you know, this free software stuff is all just a paradigm shift anyway, it would be just great if you could spend some time trying to find someone willing to pay us to use their software, and if I could manage it from my cellphone that would be great. Mmmmkay?"
include $sig;
1;
http://www.dspace.org/
"A groundbreaking digital repository system, DSpace captures, stores, indexes, preserves and redistributes an organization's research material in digital formats."
Get a giant pneumatic tube installed between corporate headquarters and each customer. Where this proves impractical, have a canal dug instead.
Then, deliver all your companies manuals on CDROM media to customers through the pneumatic shuttle in the tube, or by barge on the canal.
Store the manuals in DocBook and then dynamically create PDF, HTML, etc. as needed.
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.
Quit playing Monopoly with Bill.
Linux - of the people, by the people, and for the people.
Software? Hardware? Widgets? Vacuum cleaners?
Programmers? Engineers? Diesel mechanics? Consumers?
If the cost of Sharepoint Portal Server is too high, why not Sharepoint Windows Services? IIS6, so I assume you are Win2K3, it comes as a windows component.
.NET (you could write your webparts in Python.NET, if you really wanted to). /me zips up asbestos face mask
It has WebDAV versioning, and document libraries already setup (kind of, you will most likely want to write your own.) The development is in
Technology Consulting & Free Downloads
Just quit yer whining and use your creativity (if you have any) to code the solution.. Slashdot can't do your work for you, and shouldn't be used as such.
You keep the files as they are, and Bad Blue automatically indexes them for full text searching (supports Word, Excel and Access) and also has web listings of the files, in a portal like format.
And best of all, it's not free!
Another siimilar alternative is to use the content indexing with Microsoft Windows Server, which has more support for different file types (pdf, ppt, etc.). In conjunction with IIS, it allows you to do full text searches on the files. It's fiddly to set up though.
The friendliest digital photography forums on the net!
ReWorx allows you to convert Word documents to HTML web sites. The document is written in one Word document and marked up as per usual using styles. Reworx converts this into a series of web pages. Free trail available.
http://www.republicorp.com/reworx.htm
Scan the docs, convert from OCR/rtf to plain text. Format in XML, using a one-time exectuted, well-thought out DTD. After that, migrating the material to text, print, web, pdf, or anything else, is trivial. One source - any output. The way to go. That's what our little company does. We do military manuals. Heavy DTD, though. Most folks won't need the detail.
TextPad, on a PC, or any java-based editor, will do all the grunt work. Companies in India have the outsourced market for this kind of work pretty well sewn up, but the military and others who aren't fond of sending their data abroad, use 'local' people, like us. This would be different for those abroad, obviously, but the same principles apply.
We use a couple of our own, proprietary apps, but all the 'pieces' are out there, open-sourced, and free. (Our in-house stuff includes an organizer, a DTD insight tool, and a 'variant' we wrote for the Electronics Communication Command guys.)Here's a little tech note: The paper-based manuals on an aircraft carrier are responsible for 3 1/2 inches of water displacement, at sea. That's some serious weight factor. Similar situations arise with commercial and military aircraft. All that stuff can be traded for a handful of CDs.
OWL http://owl.sourceforge.net is an open source multi-user document repository with a shallow learning curve (our 'tech' writers were able to figure it out and start organizing things in less than two hours). Docushare is also great http://docushare.xerox.com/ds/. I worked for a 3rd Party VAR during version 1 - but it does cost. However; there is some significant third party support, including Micro Image Systems http://www.microimagesys.com. I will tell you that I worked for MIS [it's a 2-3 person company] a few years ago; they're very good people.
I think with the interesting people, their lives can't possibly be wrapped up into a nice little package.
We moved our documentation to heavily tagged XML. Then we can use simple filters and load the manuals into HTML or Quarkxpress and produce on-line and off-line versions with minimal effort.
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!
This doesn't help me (not even with LOL tacked on the end). *Why* is it out of the question? "Because it is cheap and easily workable" isn't the reason - if it is, you're doomed to failure. Furthermore, we can't help you if you don't tell us why HTML & PDF are out. What does the boss want that it doesn't deliver? What rainbow is he chasing?
Speaking as a user of online manuals, I want to regiter my disgust for special purpose, "cutesy" document storage systems. I want catagorized lists, so I don't miss something, and don't have to track it down through 15 branches of hierarchy hell. I want big pdfs, so I can download one thing and print it off *once*, and not have to download and print 20 separate "chapter" pdfs.
Here's what I would do: Save the documents as pdfs. If you need "by chapter" representations, have both - whole document and "by chapter" pdfs. If the PHB wants it in web-readable form, track down a pdf->HTML converter, and *provide both* pdf and HTML forms. Create html front ends (note plural). Lists by product, by usage type, by class (manual, whitepaper, spec sheet), etc. Use tabes to present the options to download pdf/html/full/chapter representations.
Once you have that done and organized, chase the PHB's click happy rainbow of content display, and provide it along side the simple view for those people who want to use the simple type layout.
http://haystack.lcs.mit.edu/
The above can serve as a nice front-end to Dspace.
Well first off I think its time that someone gives the "cheap, good fast; pick any 2" speech to management. A complex document repository with version control that keeps documents created in a half dozen systems presentable in a variety of radically different ways for a wide range of documents, is not going to be cheap or implementable without dedicatd staff and budget. Its just not going to happen.
I suggest you look at documentum and try and figure out a wish list for the management system. Then you going to have a few choices:
1) Have your wish list look a lot smaller than a documentum type solution (this is dropping good)
2) Buy a documentum type solution and implement it.
3) Change your document creation process so that web content delivery with printable versions is built in from the ground up. That means logical not graphical document design, so Word is out the door and you are in the world of automated document production (which is not going to be trivial either).
You are asking the impossible. Clearly your boss wants a real solution. He just doesn't understand how much work is involved in creating a real solution.
manual.txt: one big text file. convert all your graphics into ascii art. someway lock the file so its only viewable in notepad.
Fast Federal Court and I.T.C. updates