Re: Documentation Tool in Linux Environment

[Brett Leber <bleber+ -at- cs -dot- cmu -dot- edu>]

Dishaa,

I adopted DocBook at my current job, but the learning curve was 
significant. You don't need to touch XML if you use a tool such as the 
excellent XMLmind XML Editor (XXE)[1], which runs on Java; but you will 
probably need to set XSLT parameters to customize your output. (I ended 
up doing quite a bit of tweaking in XSL and CSS to get HTML and JavaHelp 
output that looked good to me.)

The main task that contributed to the steep learning curve was 
configuring the "toolchain" to transform DocBook XML to the various 
output formats. Once you're set up, transforming XML is very simple--you 
launch a short script, for example. But getting there is not really 
intuitive. I recommend Bob Stayton's book "DocBook XSL: The Complete 
Guide" [2] (available online for free) for learning how to set up the 
toolchain and deciding which tools to use.

DocBook is free, and the XSLT technologies are free as well, but there 
is 'some assembly required'. I believe XXE Professional Edition can take 
care of assembling/running the toolchain for you, so depending on your 
comfort with these technologies, with you might consider that route. 
(XXE Pro is not free.)

Lastly, I would recommend that if you go with DocBook, investigate 
DocBook v5. It's not yet an official standard, but it's simpler than 
earlier versions. It was the first version I learned, and it's well 
documented on DocBook.org [3] (though not in print).

Just some comments from a practicing DocBook-er.

Brett

[1] http://www.xmlmind.com/xmleditor/
[2] http://www.sagehill.net/docbookxsl/index.html
[3] http://docbook.org/tdg5/en/html/docbook.html




On 5/9/2007 11:33 AM, Dishaa wrote:
> Hi,
> 
> I am technical writer for a software company that requires quite a bit of documentation work for its software applications. Few things regarding the present scenario:
> 
> 
>    Currently, there are no standards or documentation in place. 
>    The direction the company wants to take is have a tool that will enable printed output and On-line Help files where the requirement maybe.
>    The office runs on a Linux environment and I was wondering which would be the best tool to use in this scenario.
>    The document categories maybe - User Manual, Developer Guide, Policies and Guidelines Manual, and so on. 
> 
> Therefore, which is the best tool considering the types of documents, the work involved - setting templates and having multiple outputs, and the environment.
> 
> I had in mind DocBook, but considering I am not well-versed in XML, would like to know the alternatives. Or is DocBook use able enough even for a beginner.
> 
> I would hugely appreciate if the soundly advised members of the community could provide valuable suggestions and recommendations.
> Gratefully,Dishaa
> 
> 
> 
> Dishaa Ganapathy 
> 215 North Ave, NE 
> Atlanta, GA 30308 
> Tel: 678-925-2072|Email: dishaag -at- yahoo -dot- com
>    
>   "The real voyage of discovery consists not in seeking new landscapes, but in having new eyes."  - Marcel Proust
> 
>  
> ---------------------------------
> Expecting? Get great news right away with email Auto-Check.
> Try the Yahoo! Mail Beta.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> Create HTML or Microsoft Word content and convert to Help file formats or 
> printed documentation. Features include support for Windows Vista & 2007 
> Microsoft Office, team authoring, plus more.
> http://www.DocToHelp.com/TechwrlList
> 
> Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
> full Unicode support. Create help files, web-based help and PDF in up
> to 106 languages with Help & Manual: http://www.helpandmanual.com
> 
> ---
> You are currently subscribed to TECHWR-L as bleber+ -at- cs -dot- cmu -dot- edu -dot- 
> 
> To unsubscribe send a blank email to 
> techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
> or visit http://lists.techwr-l.com/mailman/options/techwr-l/bleber%2B%40cs.cmu.edu
> 
> 
> To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
> 
> Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
> http://www.techwr-l.com/ for more resources and info.
> 
> 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help & Manual: http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.