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.

More Artful Testing

In the software development world we have a whole cabinet full of testing tasks that can contribute to quality work; here is a list of those most commonly used, in an approximate order of where they happen along the development cycle:

Impact Analysis
Usability testing
Code Review
Risk assessment
Stress testing
Test bed preparation
Test case creation
Test driver development
Functional testing
Regression testing
Boundary Value Analysis
Branch coverage
Error seeding
System Test
Parallel testing
Documentation Review
Integration testing
Acceptance testing
Post implementation validation

Therefore all of our software should be perfect and bug free. Right? In the real world our ability to spend time and money on software testing gets constrained however by the dynamics of staffing, skills, and delivery schedules. So much as I described in this earlier post about appropriate balance, we must carefully choose which test tools to remove from our cabinet to apply to each project. And that my friend, is why software still has bugs.

An Artful Environs

In an earlier post I discussed the vagaries of herding the cats of developers. Here I want to chat a bit about motivation of creative developers in a more diffuse sense -- about how to create the environment that allows for quality and valuable software to "materialize."

This is nearly a diametrically opposite approach to the conservative management of a formally enforced SDLC. And it only tangentially has to do with software. First, consider in general what motivates an artist: a desire to be creative, a desire for recognition, a desire to be challenged, and a desire to stand out amongst their peers. Maybe they seek glamour, or grunge, or just to make an aesthetic statement. Maybe they want to promote a socially redeeming view.

Considering the amount of demanding self-discipline, focus, sensitivity, and work that this requires, how do you create a comfortable supportive space in a world of abrupt changes, insecurities, hidden stakeholders, control freaks, and conflicting priorities?

Mostly it helps to be honest and open in your approach. You don't have to necessarily build a consensus, but it does help to lay all of your cards on the table: acknowledge both the staff needs and the strategic challenges as well as how you plan to enable the former through the onslaught of the latter.

Yeah that by itself seems like a considerable undertaking, but the mere process of discussing it with your staff and your superiors will get you on the same page. At least it will settle the expectations toward how much of the developers art you can bear under the freedom of the muses versus how much of their work must yield to the dogma of the Methodology.