Pragmatic Geographer


Graph Tracing for Water Quality Assessment

My last interlude with tracing the water system involved looking for hydrologic hazards – specifically other potential sources of water that could confound maintenance efforts.

Apparently I impressed someone enough with it to get a new trace-oriented project having to do with water quality. I’ll have a second part to this talking about my first run at it and a subsequent refactoring that I’m extremely happy with, but first I wanted to mention how I was documenting it.

As far as I can tell, the corporate standard for documentation is Microsoft Word documents. At best, these have a relatively easy to navigate table of contents and the document is stored at the same location as the topic. At worst, it has neither attribute or doesn’t exist – there is no practical difference between those two situations really. No one will ever find them – which for development projects is especially problematic.

The Don’t Repeat Yourself (DRY) principle applies outside single projects. There were some things I really wanted for the documentation I was going to produce for the product.

  • Fast, built in search. Amazing the difference this makes.
  • Something you could put up on the web with little to no fuss, but wasn’t actually a public facing website.
  • Allowed all kinds of markup, images, other resources.
  • Wiki-style editing – who changed what, when, and some measure of version control.
  • Plaintext or in some easily parsed format.
  • I could quickly convert it into Word if I caught too much flak for not using it

What I eventually settled on is called TiddlyWiki (Google, Bing, Yahoo!..I’m just certain there is a rule Web2.0 stuff requires a childish name for success). Its one HTML document, thus very portable, with a bunch of JavaScript that implements all the functionality I wanted above. It also apparently has a lively plugin community that I haven’t had time to peruse.