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