Documentation is Specification

Good software design begins with documentation.  Write the user manual first.  The design documents specify the desired outputs, and the inputs, actions, and processes that cause them.  The library of design documents will include the experience interface, the online helps, the installation guide, training manuals and tutorials, and, of course, the programmer’s references.  

One of several bad designs discussed here

Overwhelmingly, that is not how software is designed; and that is why so much of it is unsatisfying. Even programs that we find useful have annoying bugs, quirky features, and unhelpful demands. It is true that software is complicated. It is an easy claim - sort of like Goedel’s Proof - that every non-trivial program has one bug. But that is not the problem. The pain we all endure - from impatience and annoyance to angst and anger -  comes from the overarching pride - hubris - of programmers at all levels who believe that they know better than you what you want and need.

This is an old problem. In Computer Power and Human Reason: from Judgment to Calculation (1976), Joseph Weizenbaum warned of hackers whom he compared to compulsive gamblers. Driven by the superstition that one more patch will fix their problems, they stay up late, bleary-eyed and disheveled, working ever more frantically on a program they began without any reference to the substantive literature in the field in which they claim to be working. They do not know first-hand the daily lives of their users.

Typically, a project manager or systems analyst finds out from meetings what the customer wants. They even “jad the users” referring to JAD the Joint Application Development process that is supposed to bring the customer into the process. The manager or analyst prepares “design documents” of a sort that define data structures, and meta-dictionaries, language requirements, interfaces, and many other nice things, none of which actually describes how the customer will engage the system.

Even 25 years ago, Dan Bricklin - the inventor of VisiCalc - created a rapid prototyping tool called Demo. Today, RoboHelp has competitors; but RoboHelp and its competitors are not perceived as design tools. They are add-ons, paste-ins, superstitious rituals that hackers in suits (“account executives”) call upon to cure problems caused by a fundamental ignorance of the goal.  The goal was never explicitly stated. 

The user experience, the installation guide, the training materials, the online helps, those define the goal. Without them, the best we have is a good guess by an insightful and benevolent technician who imagines what they would want if they were you... which they are not.

A strong design process begins with JAD sessions, of course. In our time, it is very easy to let a customer’s own design team drive the process of creating the user interfaces, menu and dialog choices, and the building of queries and reports. Our own development team brings to this their expertise based on hard-won wisdom. User experience design and user interface design are key skills in the creation of any system. Moreover, we know that experts working alone do better than peer groups of novices.  But "better" at what? And measured how?

No silver bullet solves the problem. The process of creating information systems that meet the actual needs of the client community requires the cooperation of all contributors at every stage. Among those contributors are the documentation experts who most often are called in only when the product is ready for shipment.    

Also on Necessary Facts:
Readability is the only Metric
The Genius of Design
Objectified - a film about design by Gary Hustwit

Art & Copy: when advertising changed

Start the Presses! Typeface by Justin Nagan and Helvetica by Gary Hustwit

Programmers Night Before Christmas

I found this on a blog by Michael Boyd Clark (here) dated 10 December 1997, 1:56 pm. However, it goes back at least to the 1970s if not the 1960s. I edited some bugs.

'Twas the night before implementation and all through the house
not a program was working, not even a browse.
The programmers hung round their cubes in despair
with hopes that a miracle soon would be there.

The users were nestled all snug in their beds
while visions of inquiries danced in their heads.
When out of the tube there arose such a clatter
I sprang from my desk to see what was the matter.

And what to my wandering eyes should appear
but a super contractor with a six pack of beer.
His resume glowed with experience so rare.
He turned out great code with a bit-pushers flair.

More rapid than eagles, his programs they came -
He whistled and shouted and called them by name:
“on UPDATE, on ADD, on ENQuire, on DELete!On batch jobs,
on closing, on function complete.”

His eyes were glazed over, fingers nimble and lean
from weekends and nights spent in front of the screen.
A wink of his eye and a twist of his head
soon gave me to know I had nothing dread.

He spoke not a word but went straight to his work
turning specs into code; then he turned with a jerk
and laying his finger upon the enter key,
the system came up and worked perfectly.

The updates updated, the deletes they deleted,
the inquiries inquired, the closing completed.
He tested each whistle, he tested each bell,
and with nary an ABEND, all had gone well.

They system was finished, the tests were concluded,
the client’s last changes were even included.
And the users exclaimed with a snarl and taunted,
"IT’S JUST WHAT WE ASKED FOR, BUT NOT WHAT WE WANTED.”