As I mentioned before, we are in the middle of a rather large project - converting our Coverage data to a Geodatabase. I won’t/can’t delve too deeply into the details, but one part of the project involves making sure that we have complete and correct documentation for both our data development and application development process.
As you might imagine, we have had many long discussions about what to document and how to do it. Here is some rough thinking on my part. I welcome any ideas/comments.
Multi-tiered Documentation
Most modern application development is built upon several layers or tiers. In web design the mantra is to separate presentation from data, in desktop applications you separate the UI from the business logic, etc. I lean towards a similar approach in documentation.
In that approach we’d have the design documents, like functional specifications (call me old school, I like specs); implementation documentation (I like to call this “code” - more on that later); and user documentation.
Design Documentation
The design documents would detail several things (this is not all inclusive):
- Why the application is being created - what problem is it solving,
- Who is requesting the application
- What the application is supposed to do
- The UI
Implementation Documentation
Let’s face it, programmers hate to write documentation. I do, and I sort of have a part time job writing. So my goal for the developers I guide is simple - reduce the amount of documentation they have to write.
My basic philosophy is that the code is (for the most part) the documentation of How the application works. Even internal comments are notorious for becoming out-of-sync with the code, so an external document (which some shops demand) is only going to make matters worse. The code should be clear and concise, with meaningful naming for all components (like functions, objects, variables, etc).
I am thinking that code walk-throughs would help in this area - what is clear to you might be Klingon to someone else. I know that back in College having to defend proofs in Number Theory class really strengthened my mathematical writing and I think that anyone who has worked in a team environment has had the experience of someone asking them what the heck they were thinking in some bit of code.
User Documentation
User documentation can take the form of a user’s manual (for end users) and/or procedural/workflow documentation (for technical users).
For the typical non-developer documentation, any good technical writer can produce a good user’s manual. Heck, even a sort-of-good technical writer can do it. It’s well understood and fairly straight-forward.
The difficult thing, for me, is in writing for a different audience - those who come after and management. How do you document for disaster recovery for instance? What technical level do you write to when addressing the needs of management for their understanding.
For me, that is still a work in progress.
0 responses so far ↓
There are no comments yet...Kick things off by filling out the form below.
Leave a Comment