Artistic Communication

Technical documentation is one of the least appreciated aspects of software development -- not the written words themselves, but the process of creating them is deeply undervalued. Effective technical documentation is like a Hail Mary pass from the developer in the present to the developer in the future with the intervening crosswinds of bug fixes and changes to the business rules complicating the reception.

The developer is usually the best person to author technical documentation: he understands the implicit trail of bread crumbs that he has already left in the code for somebody else to follow. If he was involved in the project from the start then he can also relate to the politics and priorities that the team faced from the design and implementation stages.

A technical document should begin with a Background section that describes the rationale behind the project and the challenges that sufaced during design and implementation. This should alert future developers to any political or technical potholes that they should avoid.

Next an Architecture section should briefly describe data flows, timing constraints, and security layout. Next some Entity Relationship diagrams: not the whole thing but just the key tables and their relationships. Then a high-level UML and quick use-case diagram, focusing on how employee responsibilities overlap with components of the system. Finally, reference the design specifications that can, at this point, direct the developer to the whole ball of wax.

Good technical documentation isn't extraordinarily deep or complicated provided that you focus on its main intent. Sure you understand the system (because you created it), but standing at the other end of the football field a future developer can easily get buried in minutiae. Wipe away those confounding crosswinds and throw that future developer a touchdown.

The Art of the Save

I suppose no matter how much somebody tells you, regardless of their advice, until you have the unfortunate happenstance yourself you're not going to learn except by experience. I'll share the story anyway... ignore it at your own peril. The advice is simple: save your source code in three places. Yes, three. Why?

A long time ago at a faraway company I had the pleasure of developing a state-of-the-art docketing system for a corporate legal department. I did all of my development off the C drive, and then after making any major change I would pull out my 5 1/4 inch disk labeled "Legal System Backup" and copy the source code over to it.

Well the inevitable happened: I had a hard disk crash. No problem, right? At least I have a backup. But after swapping in a spanking new hard drive -- holy O'Reilly: I can't read the floppy disk. Naturally about a week later a clerk in Legal wanted to add a new feature to the system. I could only shrug. I'm so sorry: we lost the source code.

Make three copies: save one or your disk, one on the network, and one in your off-site email box. Because there's no excuse for losing the source code.

Most modern developers work in an environment with built-in source code control, such as TFS or CVS. Occasionally though I've known companies that view their SQL views and stored Procs as something less than legitimate source code. Perhaps they feel a database backup is adequate coverage for the intellectual property.

Your source code (and SQL stuff) however provides an additional benefit to your employer besides being the cogs and gears that make everything work. Its /history/ is valuable for researching bugs. So make sure you not only keep three versions of everything that is currently running, but also keep all of the prior executed versions as well.

Artistic Documentation

If programming is the meat of software development, then surely documentation must be the potatoes. Somewhat bland by itself, it still makes the main course more palatable and easier to digest. Generally all development projects have documents that describe its objectives. Depending on the size and complexity of your project, you may also have documents related to its deployment, operations, maintenance, and technical details.

Unless you are your own boss development starts by holding meetings with your sponsors to ferret out their requirements. A couple days after the meeting concludes, put together a formal document for the project sponsor to sign (sometimes called a Statement of Work) that explicitly demarcates the minimal need that the participants all agreed to. The purpose of this Statement should be to facilitate communication rather than to confine and restrain. Requirements change over time, so this initial spec should be "alive" and flexible.

On a large project you will next want to create design specifications for the programming staff. There is a balance along the path of a large project in cresting enough documentation to "float" the design without asking for so much that you sink creativity or subvert the sense of ownership. The purpose of a design specification should be to give the programmers enough guidance to plan their processing strategy and to alert them to what business rules might change or end up expanding.

Inside the actual programs we also find documentation. This is more or less hidden from everyone except the developers; its purpose is to serve as a memory aid and location tool when a developer goes back to revisit his code. You should compel the programming staff to write a reasonable amount of documentation: generally, a couple of lines of in-line comments for every ten to twenty lines of programming.

In addition, on a project that you expect to be mission-critical you should have the team develop standalone technical documentation that describes how all the pieces implement the business rules, paying attention to dependencies, configurable parameters, and reuse. The technical documentation should be clear, thorough, and detailed enough to allow a new member of the team to at least get his bearings in developing new code enhancements.

Although sometimes it does just seem like a chore or a side dish, documentation can make a big difference in the long term cost of maintaining a software system. And hey, some people like potatoes. (Some people really, really like potatoes... these are the folks who become Technical Writers.)

Artful Traceability

When you are in the actual throes of day to day production… after the development is done and you work out most of the bugs… it certainly is convenient to have some sort of end-to-end Traceability. The general concept is that every change in state or activity that has a material financial impact to the company (or its customers) should be traceable back to underlying actions.

The idea is somewhat similar to how an airline keeps track of its design and maintenance records. When a portion of the avionics fails during a landing it sure is nice to look back through the records to see what parts get linked where, and what has changed.

For example, at the end of the month you send an invoice to your customers. Where do the line items on this invoice come from: what atoms of work and activity (from a systems viewpoint) do they represent? Can you trace back from an invoice number back through shipping, fulfillment, ordering, and customer options?

Many time validation is just viewed as comparing the results of production back to the functional specs to make sure all of the business rules got implemented correctly. But validation should also be enabled for ongoing activity in a dynamically changing system, and this requires designing for traceability, from the very start.

Artistic Standards

SOPs (or as we often call them nowadays “best practices”) get the usual bum rap but I like them as an educational tool. Standards and best practices are fine to the extent that they promote a safe and productive workplace without adversely affecting a sense of job security. For example “Always use camel case” is a good standard to improve productivity. “Keep your source code in three places” is a best practice that enhances safety.

Wielding standards like an axe over your employees’ heads will only create defensive animosity. I prefer to use them as search terms when I want to find a template or an example to share with somebody. For instance I might Google “best practices SQL maintenance” and see what it returns.

If your employees feel however that the purpose of your standards is to turn them into interchangeable cogs then at best they will only implement them halfheartedly and at worst they will spoof compliance. Make positive, non-corrosive best practices your standard operating procedure.