Thursday, August 13, 2009

More graph tracing - this time for water quality.

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.
  1. Fast, built in search. Amazing the difference this makes.
  2. Something you could put up on the web with little to no fuss, but wasn't actually a public facing website.
  3. Allowed all kinds of markup, images, other resources.
  4. Wiki-style editing - who changed what, when, and some measure of version control.
  5. Plaintext or in some easily parsed format.
  6. 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.
Documentation is important to preserving the intent of any project.

3 comments:

Val said...

Great images used to illustrate your point!

Navya said...

Interesting post. Thanks for sharing.
regards
Geo-coding services

Gayathri said...

Hey..its an interesting one. The image provided was also good.

Orthoimage generation