What I want in a Wiki for software development

There are lots of wiki programs out there. I mean lots. It seems like everyone has written one, in just about every language there is.

Wikis are used a lot for software project documentation, because they’re just so easy. The barriers to jumping into a wiki and adding a page where one seems needed are so low that people dive right in with gusto. You’d think that my issue with wikis is that you end up with a huge mass of disorganized pages. That’s not it, though… with some judicious care, that mass can be turned into something useful readily enough.

My issue with wikis for software development is a problem of unknown obsolescence. The best example of this I can highlight right now is the CherryPy wiki. There’s quite a bit of potentially useful material there, but almost all of it won’t work as written in CherryPy 2.1. You go to the wiki looking for info, and you have no idea when you see a given page whether it’s applicable for the version of the software you’re using.

TurboGears documentation is all in Subversion because of this. This allows the documentation to naturally be tied to the version of the software. This also has the advantage that I can use my favorite editor and take full advantage of HTML when I’m doing docs.

Unfortunately, though, I don’t think anyone is going to check out the project just to write up some new docs. People are a lot more likely to add documentation if it’s as easy to do as updating a wiki.

We could try to give wikis branching and merging capabilities like you find in source control systems. We could also require users to go through a root canal to view our docs and see how well that goes over. Even though tools have gotten better than they were, branching and merging still seems to be a black art for many.

Perhaps there’s a simplified user interface that will do the trick. Something like this:

  • By default, a user will be browsing at the latest released version (something that is marked by an admin). Links at the top of the page will let the user choose a different version to browse.
  • Only major versions would get their own version of the wiki. In most software projects, the difference between 2.0 and 2.0.1 doesn’t involve a whole bunch of potentially breaking changes.
  • When a new version is created, the wiki starts out empty. This is important, because it needs to be very clear to someone when they may be viewing a page that is out of date.
  • If a wiki word is referenced that exists in a previous version of the software but not the current, the user can choose to start with the previous version and work from there. This way, there is a manual review step for each page.
  • The history for the “2.0” versions of a page is a separate line than the history of the “2.1” versions of a page. Usually, the documentation for an older version is just going to languish anyhow.

To me, this seems easy to use for a browser of the wiki, editor of the wiki and even for the creator of the wiki software. Sure, a big wiki with lots of pages will have a bit of pain for a major new release, but you’re only talking about a couple clicks per page for pages that don’t require any changes. It seems like a major release is a good time to review the docs.

A decent wiki with a feature like this would definitely make me move my docs out of Subversion. Let me know if one exists.

18 thoughts on “What I want in a Wiki for software development”

  1. In my view a low hanging 50% solution
    to this would seem to be if wikis would
    at least *prominently* display page creation
    and last modified times (i.e., without
    having to login/view history/etc).

    I’ve been surprised at how many don’t
    do this (e.g., the CherryPy wiki AFAICT).

  2. I’ve noticed this too — in the CherryPy wiki around the 2.0/2.1 changes, and in other projects. IMO the main contributor is wiki indifference toward metadata. The wiki essence is just hypertext — no meta-text (or subtext). Not that there’s an inherent incompatability there; it seems to be more of a cultural convention. But whatever the reason, attaching a “version” field or other domain-specific fields to a wiki page seems un-wiki-is and isn’t done.

    Personally, I actually *would* check docs out of a repository. In the long haul I think that will be easier to track and manage. But I like the questions you are asking. I wonder how the Trac people manage the versioning of *their* documentation?

  3. The codespeak (codespeak.net) wiki lives in subversion. Actually, there is no way to edit over the web which is probably not really what a wiki is intended. This model works only for a small community of developers.

    I’d like to stress what was already said by Paul: The solution is to use tags, metadata (or whatever you like to name it). Then the casual user could see immediatly, for what version the document is.
    The downside, of course, is that something like this need an active editor. Users can’t be trusted to keep metainformation up to date (at least that’s my experience).

  4. daishi is right that putting the date on the page would help. Not a great solution, but much better than nothing.

    Actually, there *is* a wiki that stores metadata:
    http://twiki.org/cgi-bin/view/TWiki/TWikiMetaData
    and it even has an input mechanism:
    http://twiki.org/cgi-bin/view/TWiki/TWikiForms

    Perhaps TWiki can solve this problem. But, I do think that the real problem is a UI one, not one of data representation. Just having the ability to put metadata on a page doesn’t make it easy to branch that page when you’re working on a new version of your software…

    Even subwiki, which uses a storage mechanism that is definitely capable of branching, does not appear to have any UI as yet for dealing with this problem.

  5. How about a way for users to browse the svn version in a well formatted web page. Add a comments section and a way to flag a section as out of date. Developers in the know would check out the article that were flagged as out fo date and follow up. When it was time to move major versions you could flag documents for review and not make them available untill they had been gone over.

    The CP wiki was very frustrating to me. There is stupp in there that is still specific to version 1.

    I don’t like wikis for documentation for just that reason. It needs to be managed and it should be set up in a way that is easy to manage and deligate out small tasks (please validate page x for me) so that it isn’t overwhelming for any one person.

  6. have you tried confluence by atlassian?
    i know, it is not open source, but it rocks!! it is not expensive and i think satisfies your requirements.

    btw, i do not work fro atlassian….

  7. I don’t think version control solves the problem particularly. Documents can linger and break in Subversion just as well as a Wiki. The answer in my mind is testable documentation. doctest does some of this — and does it well in many ways — but in the context of a web app/framework it can be hard to work with. But not impossible!

    I played around with tools for this some time ago. Sadly, I’ve let the tools linger and break, not to mention the documentation built with the. Sigh. But generally speaking I think it is achievable.

    As far as Wikis… well, textarea is the stupidest text editor ever made, and when producing serious documentation I consider it unacceptable. The whole environment is uncomfortable. And I don’t see Wikis producing good documentation. A few core people generally produce good documentation — sometimes in spite of a crappy Wiki editing interface, but not because of it — and external people add recipes and suggestions that provide important feedback. But you don’t need a Wiki to get feedback and comments.

    I think a Subversion-based system, with a easy-to-run and easy-to write documentation testing system (maybe based on doctest, but maybe not) is the most important. Then a web browser of that documentation that allows comments and annotation — maybe just limited commenting on the (fairly copious) anchors that reST inserts automatically. Those comments could go in a companion file, maybe with a tool to merge them when you want to integrate comments into the documentation. Or maybe the comments could go into the document directly, especially if you can ignore them when testing (since there’s a security risk to testing documentation from a potentially anonymous source). I’m not sure what support reST can really provide for that kind of annotation; maybe a custom directive. But anyway, that’s my opinion on the matter. That’s a tool I’d like both as a user and as a developer/documentor.

  8. I do agree with you, Ian, about textareas being the nastiest text editors around. TextMate sure blows the pants off of a textarea 🙂

    Yeah, maybe I’ve got the best setup as it is…

  9. To be honest, it feels to me like the best way to handle this is to use a wiki for the current version of the documentation and do a good job keeping it up to date. Then for past versions, you can archive the documentation in some form at the point when you’re about to begin the next round of development.

    You might do this by making a copy of all of the wiki documentation and moving it to its own wiki or area of the wiki. You might do this with an exported HTML / PDF. You could even doi it by exporting the content /into/ subversion.

    I’d be curious to see a wiki with better integration with source control systems, though, I admit. But I’m pretty happy with Confluence, so it would take a compelling set of features to convince me.

  10. Many wikis have a way to keep multiple separate “webs”. If they provided an easy way to copy a page from one web to another, that would pretty much do what I’m asking about.

    That said, I am swayed by Ian’s argument and the fact that I’m about to have to do a global search and replace on the docs. Doing that with a through-the-web wiki is nasty to think about… doing that in TextMate is a pleasant thought.

    The best bet may very well be to just go and keep the docs in Subversion, and to monitor the mailing list carefully to be sure that stuff that’s coming up there is landing, in some form, in the documentation.

  11. Although wikis are great sfor some kind of information, trusting the community to write complete docs that way probably won’t work that well. I think you should consider the model of php.net instead, one entry for each function with examples of use and a comment system that lets user provide better ways of solving problems or asking for clarifications.

    For tutorials you usually want one person with a consistent style write it initially anyway. A wiki can help in that it allows anyone to write one without hassle and that people can correct grammar and factual misstakes as easily. A normal wiki probably do well for theese since there isn’t very many of them, just make sure to label each page with compatible versions, if you use namespaces for that(or “webs”) you can easily hack the wiki to allow “branching” and links to older versions.

  12. Interesting thought about keeping the documentation for previous revisions. We use Trac, just like CherryPy does.

    Another quick-and-dirty way of approaching this is to create a Wiki hierarchy for each revision. For instance, /Ver1.x/DocPage1, then with new revisions, /Ver2.x/DocPage1. The TitleIndex could be used to establish of a list of exported pages, or the entire wiki could be exported to files. An initial version of documentation could be created for Ver2.x by using the pages for Rev1.x, doing some global search/replace and basic changes, then importing them under the Rev2.x hierarchy. Each revision starts out “clean” because there are no pages under that hierarchy at the start. (I’ve never actually done this, by the way.)

    Another approach could be to have a “current documentation” area (/Doc/xxx or just /xxx), export those pages at each major revision, importing them under the pages for a specific revision (/Ver1.x/xxx), of course updating the internal page links along the way. You keep all revision history for the mainline documentation in that case, and start over for the archived copy. Somehow this makes better sense to me, since the active documentation is always at the same location.

  13. As a partial answer to the issue, I would suggest distinguishing between detail documentation and high level documentation.

    For detail documentation of software, I believe it works best to generate the documentation from the commented source code itself using a tool such as Doxygen (http://www.stack.nl/~dimitri/doxygen/ ). The result will be far more informative and more accurate and reliable with regard to the hard details than anything you would care to produce by hand, plus it can be kept automatically current with the current code base. The developer working on a file will have that file checked out already, so there is no necessary additional checkout/checkin burden to revise comments at the same time.

    The weak point tends to be for more general themes and pieces of information that are not closely tied to specific actual code. To easily and readily tie all the details together with a larger general picture — perhaps that might be a place where a wiki could supplement the auto generated detail documentation.

    The key then is tying the two together so that each can contribute what it does best. Using interwiki references (e.g. “this” for local reference) might be one way to do that.

    In the above scenario, the wiki is used for more general or large picture aspects of the system that are not tied closely to the fast changing small details of the code. Those general pages could/should have a reasonably longer lifetime than the code and generated documentation that changes with each release.

    Can anyone think of a better way to easily supplement autogenerated documentation than with an integrated wiki? Difficult/awkward procedures simply don’t get done.

Comments are closed.