Minimalistic tools for developer documentation

Question

I am currently working on a large PHP CMS / Framework and documenting it extensively as I go along. In addition to phpdoc-style inline comments, I need to document XML structures, details on concepts and practices, write HOWTOs and so on.

At the moment, I am using simple OpenOffice documents for that, but I'm unhappy with it and looking for a "real" documentation system.

So, I am looking for recommendations for robust, minimalistic, easy-to-use documentation software.

I have tried a number of Wikis, most prominently Dokuwiki. I like the open-minded approach, the freedom in editing, and the simplicity, but they provide little support in structuring a multi-chapter documentation, and make basic reorganisation tasks very difficult (e.g. moving pages to a different namespace). Working with the plugins is cumbersome, and they are not really easy to use.

So, I am looking for a solution that combines freedom with support for a clean structure.

Open Source would be a plus but is not a requirement.

Thanks for all the suggestions. I have not had time to look into each one in detail. I will be trying Sphinx, especially because it provides so much support for a good structure. I may update this post later when I'm done and report how it worked out.

---

The suggestions

Trac's built-in wiki which is great but for my taste provides too little support for keeping a structure - it's perfect though for "normal", smaller size project documentation

Markdown my current favourite because of its minimalism, however not sure yet whether maintaining a structure will be easy enough. A Markdown-Based system would of course be very easy to extend, e.g. to look up cross references from the project's code base. Of course it would be great to find something that already has that out of the box.

The DocBook format and to edit, the commercial Oxygen XML Editor - a great standard for building documentation, no doubt. Maybe too "technical" for my purposes as I need something to open quickly, write into and go on coding. Still always worth a mention.

Sphinx an Open Source, Python based documentation generator, promising structured documentation and extensive cross-referencing. Interesting and will take a look.

Confluence a commercial but very affordable Wiki.

XWiki, an Open Source playing in Confluence's league with numerous extensions and connectors to Eclipse and Microsoft Office.

TiddlyWiki an open-source Wiki.

Answer 1

Within our company we use a Wiki to document everything that doesn't fit within the PHPDoc comments.

Answer 2

I'm using the Trac built-in wiki system to document my ideas and such. It's freely available.

Answer 3

When we needed some documentation we used plain text with Markdown formatting. The people you work with can use any platform and any tools they want, the documentation can be easily versioned and diffed and you can create a nice HTML version if you want to. With a little postprocessing you can do things like TODO markers and such. It’s not a solution for everybody and everything, but it’s quite simple and gets you a long way.

Answer 4

On my last project, I used a TiddlyWiki kept in my Dropbox. Unfortunately the client hated it and insisted I turn it into a sequential Word document. Which she then proceeded to never read and bothered me with questions day after day after day. That's life as a consultant, I guess.

Answer 5

For developer documentation I use Confluence wiki. For end-user documentation, we have a custom support center built on Drupal. Web applications link directly to the support sites within the Drupal app or use RSS feeds to provide article titles and links. I also use jQuery plugins (tooltip) to provide extensive inline documentation via hover overs.

Answer 6

Sphinx is a tool for writing developer documentation. The documentation is written using a simple markup (called restructured text). Your documentation can be arranged in multiple files and folders hierarchically. Sphinx will generate different versions of documentation (HTML, CHM, PDF, etc.) from your documentation source files. Naturally your .rst files (restructured text files) can be checked in a version control system and multiple people can collaborate on one documentation project just like they collaborate on a software project. There is no Wiki involved, hence no limitations of through the web editing.

The tool is quite popular in Python world though it is not specifically tied for Python only documentation. You may consider giving it a look.

Answer 7

I don't know if this is the solution for you but, in my opinion, any thread about writing technical books and articles should at least mention DocBook. Quoting the C2 wiki DocBook page:

DocBook is a StandardGeneralizedMarkupLanguage (and now ExtensibleMarkupLanguage) DocumentTypeDefinition (DTD) for writing technical books and articles. It is very mature, having been developed for over ten years. It has a mature tool-chain that can be used to translate DocBook documents into other formats for type setting or online presentation, including TeX, PDF, PostScript, HTML, Microsoft HTML Help, and TROFF. O'Reilly use DocBook to author their books and it is the standard documentation format for several computer vendors and for various Linux and OpenSource projects.

If you know XML or HTML, DocBook is easy to learn. Since it was designed to handle large documentation projects, it feels more logical and is more carefully designed than HTML. However, it is much larger, more complicated, and more narrowly focused than HTML: the DTD defines hundreds of markup elements for specifying the structure of books and technical computer documentation. It is designed to mark up text, hyperlinks and embedded media (like HTML) but can also be used to generate table of contents and indexes.

There is a Simplified DocBook DTD that is useful for online documents, and has a reduced number of elements.

DocBook has a long and varied history (it started as SGML DTD and is now an XML DTD) and has been used by many different companies (from O'Reilly to Boeing to the LinuxDocumentationProject to the Pentagon) to create many different types of output (PostScript, PDF, RichTextFormat, plain old Text, HTML, and PalmPilot doc files).

Regarding tools to work with DocBook XML Documents, this question is actually a recurrent question on the docbook-apps mailing list so you might want to search the archives. You'll find out that oXygen XML is one of the (commercial) tool offering the best built-in support and a full graphical interface. But there are of course alternatives.

Answer 8

Just because Confluence as been mentioned, I'd like to add XWiki to the list, a serious alternative to Confluence. It is another very good and very nice enterprise wiki, it has some nice plugins, is highly extensible, has nice companion applications like XWiki Eclipse or XWiki Office that you may find handy (especially for bulk reorganization of pages or creating larger documents).

Answer 9

Check out Doqua, an Eclipse plugin intended to help developers stay on top of documentation.

_{Full disclosure: Yes, our company puts out that product...}

Answer 10

'''UPDATE''': Quiki is now under active development.

How about this idea (probably not original):

1. You write your documentation as simple wikitext files and keep them in your source repository together with the source code. This way the documentation live together with the source code, and can be branched and merged easily.
2. You can use wiki links to link between various page as you would on an online wiki.
3. You generate the actual documentation using a command line tool as part of your build process. You get a set of HTML pages/files (or even a single aggregated HTML page) which you can upload to a web server and/or package together with binaries.
4. You can use wiki templates (like MediaWiki's) and wiki categories to insert various auto-generated parts of the documentation (version numbers, source code examples, tables of content, indices, etc...).
5. The tool can check for inconsistencies in the documentation, like broken links.

This idea came up few days ago after reading all the suggestions, none of which satisfied me. I've written a lot of Word documents, Wiki pages, static HTML pages, but all of them suffer from one problem or the other. So far Wiki documentation was the best option for me, since the wikitext syntax is simple enough, but I don't like the fact that the documentation lives separately from my software.

I've started a new project on Google Code called Quiki.

Answer 11

I use Confluence at work and cannot recommend it in light of the criteria mentioned.

Confluence main failure is at the core - ease of editing. The wiki syntax forces excessive quoting, it does not support section editing, the default code blocks are broken for Java and C++ and the list goes on. On the other hand, The WYSIWYG editor is a pain to use for anything beyond the most basic of documents and the wiki syntax created is unreadable.

I would recommend looking at DokuWiki which we used before and made the unfortunate mistake of replacing.