3

My company currently maintains our technical documentation (User's Guide) in Google Docs. With each release I produce a PDF that we host on our website.

Here are the features of Google Docs that work well:

  • Collaboration: Multiple simultaneous editors, comment/reply/resolve system
  • Ease of use: Cloud based, built-in backups and revision history
  • Features: WYSIWYG editing, Table of Contents

And the not so nice:

  • Inability to produce an index
  • Limited styling capabilities
  • Limited HTML export capability

I'm tasked with finding a new "tool" that supports the following needs:

  • It must produce HTML with the classic left-pane-navigation / right-pane-content model
  • Functionally, it must support index creation (for both PDF and HTML), and more powerful styling

I'm open to ideas with respect to platform, though I'd love something cloud based.

Improve this question
2
  • How large of a shop are you looking at? How many users/concurrent users?
    – James
    Jan 16, 2014 at 14:58
  • We are 8 engineers, and no more than 4 do any editing. I just want to make sure the tool supports > 1.
    – tmcallaghan
    Jan 16, 2014 at 15:02

5 Answers 5

Reset to default
2

Here's what we do for that. It's not cloud-based, but it is source-control-backed, like (I hope) your code already is.

Tools and technologies involved:

  • source control

  • DocBook DTD

  • your favorite editor for XML files (WYSIWYG possible)

  • XSLTProc (with ant, but you could do make or something else instead)

  • XEP (PDF generator)

  • (deprecated, but I'll mention it anyway): HTMLHelp Compiler

We write our documentation source against the DocBook DTD. This is a well-established documentation standard, and while the whole spec is big, you probably only need about 20 XML elements (tags). All the usual stuff is there -- divisions (book, chapter, section, etc), formatting (emphasis, code, etc), semantics (classname, methodname, command, guielement, etc), indexing, TOC, and so on.

Alongside the DocBook XML source are stylesheets that translate your XML input into whatever output you like. DocBook comes with some of these. We feed the XML source and the stylesheets to XSLTProc to produce an intermediate output, formatting objects (FO). We then have a step to transform that into PDF (using XEP), HTML (using XSLTProc), and (we don't do this part any more) a CHM file of HTML doc (using HTMLHelp Compiler).

We pack all those generation steps up into an ant build file (ant is what we use for our software builds already), but there's no reason you couldn't do it through make or whatever your build tool of choice is.

The XML source is checked into source control and collaboration is accomplished in the usual way. XML supports file inclusion, so you can modularize your books however you like. Because the docs are in our source-control system, it's easy to branch and tag them, and the automated nightly builds include documentation.

Because the source is XML, not some binary format, diff and merge work as you would expect, and you can use whatever editor you like. Some of our people use Abortext Epic (pretty high-end), some use Oxygen, some use NotePad+XML, and at least one old-fashioned person (ahem) uses emacs.

Improve this answer
1
  • It's three years later and I'm at a different company with a different tool chain, maybe easier than this (but $$$). I'll try to remember to write it up later, but am leaving this comment in the meantime.
    – Monica Cellio
    Jan 27, 2017 at 22:10
2

So I may be inferring to much from your question but...

It may be worth your time to look at a collaboration suite...with a shop that small it wont cost much and the tools offer cloud storage and versioning, web publication, you can edit the documents from the tool...approvals, sharing, discussions, all sorts of stuff. Now these are...peripheral to whatever tool actually creates the document. So you could host a word doc or a pdf in the cloud on one of these tools (Word can manage all the items you listed) I have not seen a tool that both creates and publishes documents (at least not effectively...) they may be integrated and from the same provider but its usually two tools.

So I guess my suggestion boils down to, use the document creation tool you want and then use a collaboration tool to manage publishing, reviews, concurrent work etc...

Take a look at some of the following.

Atlassian Confluence

This tool is 10/user/month offers document sharing and collaboration.

Huddle

Huddle is a little more expensive, 20/User/Month, but is very feature rich...it can do all sorts of cool stuff including pre-built apps for mobile access.

Perforce Commons

This one is a little less robust but is free for up to 20 users.

Hopefully this helps, if I am way off target let me know, I can always remove this answer.

Improve this answer
2

I would say you're looking for a cloud-based help authoring tool (HAT), whether a SaaS or hosted on servers on your company premises.

We've used WebWorks ePublisher, which outputs to several kinds of HTML formats (e.g., WebWorks' own HTML output, HTML Help, etc.). It also offers on-premise cloud hosting (CloudDrafts). Its main strength is the sheer number of outputs it offers, which might be overkill in your case but worth looking at nevertheless.

You might also consider some SaaS solutions like ClickHelp. Some vendors like MadCap Software offer their HATs in combination with an additional solution you must purchase to make it cloud based.

I have a further list of SaaS HATs on DocToolHub if you're interested... just select the filters for "help authoring tools," "SaaS," and "PDF."

Improve this answer
1

If you want to support documentation for multiple products, content reuse (in a more efficient manner than copy&paste) becomes desirable. If that's the case, a tool like Author-it fits your requirements: multiple output formats including PDF and HTML, proper book formatting (TOC, index, etc), highly customizable styles.

Its collaboration features are structured a bit differently from the Google Docs model: one author can work on a piece of text at a time, but that piece of text can be small (one section). The writer sets up a review workflow where others can comment, but not directly change the source. This prevents edit wars and screwing up painstakingly-written content by amateurs.

What sets it apart from the usual office collaboration tools is the ability to reuse content from single sentences to entire chapters. This saves a lot of time if you create documentation for multiple products.

Improve this answer
0

We have been using Help & Manual for seven years. Has approximately 8 output formats, uses XML as back end, integrates fine with svn and is easily translated using OmegaT. Allows concurrent user licenses (we have two).

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.