Become a fan of Slashdot on Facebook

 



Forgot your password?
typodupeerror
×

Comment Knowledgebase toolsets (Score 1) 401

Having been a technical writer in the computer industry for over twenty years, I can tell you from experience that the best approach is to (1) set up a wiki for technical folks to contribute content and simultaneously (2) use a professional technical writer to build and maintain a knowledgebase drawn from that wiki content and code comments, plus their own interviews, research, diagramming, and writing.

Do not try to solve this problem using traditional desktop publishing tools, except as a short-term stop-gap measure. Find a technical writer who understands both relational database and XML technology, and put them to work using their preferred toolset.

Some knowledgebase toolset notes follow.

Adobe RoboHelp Server 8 can be the delivery mechanism for an enterprise-wide knowledgebase and RoboHelp 8 can be the authoring environment --

http://www.adobe.com/products/robohelp/

http://www.adobe.com/products/robohelpserver/

with various additional authoring and diagramming tools serving as content creation editors, especially to cope with producing documents needed urgently, albeit in desktop publishing mode.

While RoboHelp got its start as a Windows online help editor, it has, like the gawky teenager next door, grown into an impressive adult over the past few years.

A competing product you (and your technical writer) should also look at is Macap Flare, which was developed by a group of software developers who spun off from RoboHelp a while back.

(RoboHelp had been successively owned by Blue Sky, eHelp, Macromedia, and now Adobe, with the all the personal stress such corporate buy-outs, and the resulting rebranding code-churn, can induce.)

Madcap Flare is also part of a knowledgebase-creation toolset that will soon have its own content management server as a delivery and workflow mechanism --

http://www.madcapsoftware.com/products/flare/

http://www.madcapsoftware.com/products/teamserver/

The Altova XMLSpy toolset is also worth evaluating --

http://www.altova.com/solutions_center.html

Don't expect your techies to spend their time in Altova, Flare, RoboHelp (or whatever), since their time is much better spent writing code and comments and any descriptions they can generate, in tools they already know and love, such as wikis and their favorite IDEs.

But do expect your technical writer to follow along and clean things up in a high-end knowledgebase toolset, and, eventually, to set up a workflow process for copyediting and approving new and updated material, but in as unobtrusive a manner as possible.

Also be aware that your knowledgebase will likely need to be translated into multiple languages, with the advice and assistance of localization specialists.

It sounds like your technical writer will be doing catch-up -- it has typically taken me about 18 months to get things under control and flowing smoothly in any company that neglected to hire a technical writer from the beginning, all the while jamming out whatever documents were needed for product delivery using standard desktop publishing tools.

This is not a life to envy, or for the faint of heart, but it can be an adventure for the truly dedicated. Bringing order out of chaos with your keyboard can be a rush.

Comment Re:Exploratorium Cookbooks (Score 3, Informative) 249

To save you some digging, here are the direct links for buying each of the volumes directly from the Exploratorium itself (these show up when you search that website) -- http://store.exploratorium.edu/browse.cfm/4,622.html and http://store.exploratorium.edu/browse.cfm/4,775.html and http://store.exploratorium.edu/browse.cfm/4,760.html and for all three as a [discounted] full set (for $350) -- http://store.exploratorium.edu/browse.cfm/4,19.html These may be overkill for your immediate needs, but if you are ever tasked with starting your own hands-on science museum, the Exploratorium folks have very kindly documented their approach.

Comment Exploratorium Cookbooks (Score 2, Informative) 249

The San Francisco Exploratorium, an interactive, hands-on science museum, published a three-volume set of instructions for creating useful and educational (and sturdy) projects for children and adults to manipulate and study, although these are now hard to find, and expensive. Search the used books website http://www.abebooks.com/ for "Exploratorium Cookbook" (and grab any copies you can) and see also the Exploratorium website at http://www.exploratorium.edu/ . See also the very recently published book "Laboratory Experiments in College Physics" by C. Bernard and C. Epp, published in December 2008 (ISBN 978-0471002512) available on http://www.amazon.com./

Slashdot Top Deals

BLISS is ignorance.

Working...