I’m a big fan of keeping stuff in a simple textual format (even more so since reading The Pragmatic Programmer). So on our little startup project we’ve simply been keeping the documentation in text files. The project to-do list, installation instructions, all that sorta stuff. There’s only two developers on the project at the moment, so we just sync up to CVS and we get the latest gear.
Well I’ve started doing doco for more serious stuff on coding internals, and decided it would be cool to hyperlink from one text doc to another… but I didn’t want to start marking everything up to html. Too much overhead… and overhead means another reason to stop me documenting. But I also didn’t really want the overhead of a full blown wiki right now… another thing to manage/secure/backup/administer… and I would have to leave the IDE to update the docs… giving me another reason to not document while it’s fresh. So text files have been serving me pretty well.
Enter EclipseWiki: a very cool eclipse plugin that will treat any text document in your project with a .wiki extension as being a Wiki doc. It will mark up your CamelCase links to the related CamelCase.wiki text file. And it will even mark up references to your class files as a link the class file itself in the IDE (so you can just use Ctrl-Space in the text editor, select your class, and you get a hyperlink to the real class).
As shown above, the EclipseWiki view has some tabs at the bottom to switch between editing, browsing, and help, and you can choose from three wiki formats (Ward’s Wiki, TWiki, and SnipSnap). Sweet.
Overall a very cool little plugin. I preserve my simple and easily editable text format that I can hack straight from my IDE while I’m there… and I get the benefits of having a Wiki framework to make it look pretty and link it all together. And down the track if we need to move to a full blown wiki, it’s just going to be cut and paste.
Great work guys. Recommended.