Documenting your architecture is one of the holy grails of software development. While programmers tend to put effort into practicing commenting source code. Providing good system architecture design documents and sample code tends to be the challenging next step. This is because it's time consuming. While lot's of different hands in the pie, it becomes a valiant effort to get contributors to update the documents.
Wikis have provided a great step towards solving this problem. No longer would you have to navigate a 500 page Microsoft Word document looking for obsolete documentation. With Wikis you can collaboratively write and link different articles and samples together. The only problem remaining is that damn frustrating markup language Wikis use. The premier Wiki engine MediaWiki doesn't support WYSIWYG editing by default, which means creating documentation becomes more of a chore.
Here I will document my search for an easy WYSIWYG (what you see if what you get) editable Wiki engine and compare my findings.
WYSIWYG Wiki (http://www.wysiwygwiki.org/)
Allows you to modify pages using AJAX (try it), it's awesome. The only problem is that when you download it, you realize that you need to create your html pages manually, then include snippets of code in the header of the page you wish to modify.
Foswiki (http://foswiki.org/)
The website looks great, highlighting it's implementation of a World Class text editor.
But, I'll be honest and admit that I was scared off by the set up instructions.
MediaWiki (http://www.mediawiki.org/wiki/MediaWiki)
While MediaWiki just released a WYSIWYG editor, it only gives you an editing bar with the preview still showing wiki markup.
You can use Microsoft Word to export wiki marked up documents, although you'll probably need to do some editorial work when using images.
There' is an editor plugin for MediaWiki, however it only supports version 1.16-17 and of course may not work as desired out of the box.
Wikiwig (http://wikiwig.sourceforge.net/)
The best thing about using this Wiki engine is how each it is to set up. You simply, download the package, unzip it onto your webserver, setup a database for it. Then navigate to the page and it'll greet you with a configuration screen with a one click set up process.
On this screen you specify the name and credentials for the database. Note, if your web server doesn't support https, make sure you change the login/sign option to use http instead as no error will be reported until it's too late.
Another thing to note is that if you're using a newer version of php you'll get a couple of warnings when it's set up.
However, you can simply update the script in _wk/lib/Wiki_Db.php to remove the warning (or ignore it).
Feature wise, it's really simple to create and edit a new page. You can even directly insert HTML. While it may not be the best for security. It's great to actually get going with documentation.
Conclusion
Wikiwig was last updated in 2008, but I'm happy it exists. For my needs (software documentation), it's perfect. For a more comprehensive Wiki engine I'd suggest looking into the other options presented above with bias towards MediaWiki as it's the most recognized brand.
Wikis have provided a great step towards solving this problem. No longer would you have to navigate a 500 page Microsoft Word document looking for obsolete documentation. With Wikis you can collaboratively write and link different articles and samples together. The only problem remaining is that damn frustrating markup language Wikis use. The premier Wiki engine MediaWiki doesn't support WYSIWYG editing by default, which means creating documentation becomes more of a chore.
Here I will document my search for an easy WYSIWYG (what you see if what you get) editable Wiki engine and compare my findings.
WYSIWYG Wiki (http://www.wysiwygwiki.org/)
Allows you to modify pages using AJAX (try it), it's awesome. The only problem is that when you download it, you realize that you need to create your html pages manually, then include snippets of code in the header of the page you wish to modify.
Foswiki (http://foswiki.org/)
The website looks great, highlighting it's implementation of a World Class text editor.
Note this is only part 1
If anyone has used this Wiki, it'd be great to hear your thoughts.
MediaWiki (http://www.mediawiki.org/wiki/MediaWiki)
While MediaWiki just released a WYSIWYG editor, it only gives you an editing bar with the preview still showing wiki markup.
You can use Microsoft Word to export wiki marked up documents, although you'll probably need to do some editorial work when using images.
Wikiwig (http://wikiwig.sourceforge.net/)
The best thing about using this Wiki engine is how each it is to set up. You simply, download the package, unzip it onto your webserver, setup a database for it. Then navigate to the page and it'll greet you with a configuration screen with a one click set up process.
On this screen you specify the name and credentials for the database. Note, if your web server doesn't support https, make sure you change the login/sign option to use http instead as no error will be reported until it's too late.
Another thing to note is that if you're using a newer version of php you'll get a couple of warnings when it's set up.
However, you can simply update the script in _wk/lib/Wiki_Db.php to remove the warning (or ignore it).
Conclusion
Wikiwig was last updated in 2008, but I'm happy it exists. For my needs (software documentation), it's perfect. For a more comprehensive Wiki engine I'd suggest looking into the other options presented above with bias towards MediaWiki as it's the most recognized brand.
nice summary :)
ReplyDeletefor a awesome example of software documentation have a look at the backbone annotated source code :)
http://documentcloud.github.com/backbone/docs/backbone.html
of course that wouldn't work for architecture and backbone is rather small but... man never seen a project that documented