What tools does your team use for writing user manuals? [closed]

StackOverflow https://stackoverflow.com/questions/314117

Question

Basic requests are:

  • human readable / text format (for easy version control)
  • online (for collaboration)
  • easy formatting (markdown ok, html is too much)
  • strict formatting (so authors don't invent new types of titles, bullets etc.)
  • exportable to PDF, HTML
  • easy backup and deployment (so we can "deploy" to customers site as read only version)

We are thinking about using some kind of wiki engine, but it would need to use files for storage or have other means of "deployment" to customer and be easy to install/maintan. Also, it would have to be free / cheap (confluence is way too expensive)

Any suggestions?

Edit: I'm not looking for tools to document code, we have that covered using Sandcastle.

Was it helpful?

Solution

Although it may not answer all your requests, DokuWiki may be worth taking a look at.

As with other wikis, it has a simple syntax, and has version control to track revisions, generates table of contents, and a full-text search feature which can come handy for a help system.

You may want to evaluate the feature list to see if it will meet your needs.

Also, there seems to also be a good collection of avaialble plugins. Although I haven't used DokuWiki or its plugins, there seems to be plugins available for PDF export as well.

OTHER TIPS

For our API, we use Doxygen, which is great.

Pandoc is a fantastic tool for converting between various markup formats. We write docs in markdown and use Pandoc to convert to other formats.

From the pandoc site:

If you need to convert files from one markup format into another, pandoc is your swiss-army knife. Pandoc can read markdown and (subsets of) reStructuredText, textile, HTML, and LaTeX, and it can write plain text, markdown, reStructuredText, HTML, LaTeX, ConTeXt, PDF, RTF, DocBook XML, OpenDocument XML, ODT, GNU Texinfo, MediaWiki markup, textile, groff man pages, Emacs org-mode, EPUB ebooks, and S5 and Slidy HTML slide shows. PDF output (via LaTeX) is also supported with the included markdown2pdf wrapper script.

Pandoc gets extra points for being open source and written in the hotness that is Haskell ;)

I can not say enough good things about Asciidoc. It has a very simple markup syntax, can generate everything from pdf to roff, portable to implement and very easily inserted into any wiki with only a few minor changes.

Even in its markup state, its very, very easy to read. The only thing I have to fiddle with when using it are tables, but that's not too difficult.

If you keep the text formatted files in your repository, revision tracking is quite simple.

For code documentation, I use doxygen.

We use help and manual for manual and help file. There is no html export, but it provides html help, winhelp, pdf and some more formats.

We're using a wiki. I recommend MoinMoin because

  • very simple to setup (even on a Laptop)
  • very simple to backup (you can even commit the wiki to a version control system to sync it between, say, laptops for offline usage).
  • nice syntax
  • easy to extend
  • Easy to search

We're not using something like Word because:

  • Documentation rots too fast
  • Searching all documents is a pain
  • Linking between information bits is a pain
  • No diff between versions
  • Binary format which craps the hell out of any VCS
  • No deep bookmarks
  • Documents grow too big and then they become clumsy: Split (and no searching anymore) or wait ages to load.

You don't mention the language/framework that you are using. There are really good documentation tools out there, but some of them are specific to what you are developing in. We are a C# shop, so my answer will only apply to you if you are using .NET.

We use Sandcastle, which is not only free, but open source. While people primarily think of it as strictly an application that generates documentation from XML Documentation, you can provide your own content in MAML. It can target both CHM and web site deployments, which meets our needs. There are some additional tools that can provide things such as marking favorites and topic ratings to my understanding, but we have not started using them as of yet.

This provides us with both internal and external documentation. Since we also use Team Foundation Server, we use the built in Wiki on the Team Project in Sharepoint, but that is more geared towards project collaboration.

Edit: Fixed broken link, and also wanted to mention that there are other tools in conjunction with Sandcastle, that we use. Things such as Sandcastle Help File Builder and GhostDoc are common tools. The first to edit the Sandcastle projects and MAML, and the second to improve comment quality in the code.

Try Sphinx. All python documentation is made using this tool http://docs.python.org/

For "manuals", Docbook. It's an SGML dialect designed for technical documentation. http://www.docbook.org/ . It may not meet your "easy markup" criterion but it definitely produces nice output in LaTex (can be converted then to PDF) and good HTML output if you cook up your own CSS stylesheet for it. Text files kept in version control. All programs also use a library that combines command line argument parsing with "--help" output in a choice of formats (normal, man page, and docbook). For the API reference, doxygen of course.

At my current job we churn out single-use software so documentation often gets put on the sideline and is done in Word.

At my last job, however, the documentation team seemed to continuously rant and rave about mad cap software's product "Flare". It allows you to write in one format and publish to many mediums so your manual can also be your online help or a website, etc...

try Dikiwiki

We use Word. It gets put into our version control, so we have history (there's a documentation folder linked to every project). Formatting can be controlled using templates, all of which we now have set up, so making changes is easy to do within the layout standards. The files can be exported to PDF. You can publish them as read-only docs for sharing with users.

We've had great success with DocToHelp. It works great with Microsoft Word based documentation as well as other forms, and it's even got some great integration features for Visual Studio.

The best part is once you've got a core document base imported into DocToHelp, you can choose any one of a number of export formats be it WinHelp, HTML Help, Java Help or the nice and fancy searchable Net Help.

For doument the code I use Doxigen. I prefer the linux version, I had have problems with a few features in the Windows version

My company uses MediaWiki and TikiWiki for most documentation. We also have a guy that compiles stuff into MS Word and PDF formats for printing/sending to customers. I'd recommend you avoid TikiWiki like the plague. MediaWiki is great, both because it is really easy to use and because everyone knows how to use it -- it's the de facto standard wiki, and deservedly so, IMHO.

For some time we were using DocBook, but it was very hard to extend with more advanced, and necessary features (syntax highlighting, splitting into several files, multilinguality management etc.). Later, we decided to write our own system from scratch and release it as open-source: link text. It uses plain text files and Markdown as the syntax language, and now we have everything we need. The disadvantage is that currently there is probably no Markdown parser that produces something else than HTML output. For now this is enough, but we are thinking about implementing PDF support quite soon.

Moreover, we are maintaing MediaWiki as a community-based help.

Licensed under: CC-BY-SA with attribution
Not affiliated with StackOverflow
scroll top