User Manual Driven Development

Posted by johnreynolds on September 5, 2008 at 9:32 AM PDT

One of the best jobs that I ever had was back in the mid-80's working for Scott Cutler at Tandy Electronics Research and Development. I worked on the team that built the DeskMate II GUI shell and its associated applications. This was back in the glory days when many vendors were still pushing their own graphical environments - Apple clearly in the lead - Windows not yet quite measuring up - Atari andDigital Research's GEM still viable contenders.
We wrote everything in C and 8086 assembler... Life before objects: Smalltalk was around but too much of a resource hog for the Tandy 1000 (256K of RAM and a 5 1/4" floppy). C++ was just a rumor as far as we were concerned... Structured programming was king.
Our development methodology was simple but effective... the marketing group wrote the deskmate user manual and we built the applications to match the manual. To be more precise, the marketing group would write a proposed manual, we'd negotiate with them over what could and what couldn't be done, and then we'd build to the manual.
I guess you could call this User Manual Driven Development, and I think that it still can be a very valid approach. In most respects User Manual Driven Development is very close in spirit to Test Driven Development - The function of the software is clearly defined, so it's very clear if the software doesn't do what it is supposed to.
Some time between the 80's and now we mostly abandoned the idea of User Manuals. Let's face it... few users ever bothered to read the manual (Leading to the ever present RTFM reply on many support forums). Few companies even bother much with online help... Users are mostly encouraged to just play with the software and learn by doing.
I'm not advocating a return to User Manuals... but I do advocate tailoring our development methodologies to return the programmers focus back to the users. The prime objective is always to satisfy the needs of the users... The users really don't care about object hierarchies, they don't care about Java vs. Ruby. They care about being able to do what they need to do.
I think most of you will agree that some of the best software that you can find is software that is primarily used by programmers. Eclipse,NetBeans, Visual Studio... This comes as no surprise: Programmers understand the needs of other programmers. Since I understand the purpose of the software, and I know how I would like it to work, then I am extremely qualified and motivated to develop the application.
It always stuns me when I encounter an engineering manager who believes that his staff doesn't need to know how to use the product that they are developing. I've heard people say "Just give us the requirements an we'll build it". I simply cannot agree with this philosophy... Requirements are never enough. Ever.
To write great software, you have to put yourself in the shoes of the user and walk a few miles. Perhaps it's a bit like method acting... Unless you "become" the user you're just going through the motions.
Related Topics >>
Blog Links >>

Comments

by staubsaugernz - 2008-09-08 13:24
Writing software so that no user manual is required is an ideal but for non-trivial applications a manual is often required. Otherwise users will not become proficient with *all* the features of the software. For example, the manual should document what valid parameters are and provide definitions of what everything in the GUI does, and specific meanings of words. These are things you cannot get from a purely ad-hoc 'trial and error' approach to learning how to use a system. If humans interact with the software (it is not a purely business-2-business service) then the software should *always* be written with the user's point of view in mind. Mocking up the manual first is a very good way to do this, but hard to sell developers/managers on this. However, it helps the software development process since developers are *forced* to think about how parts of the system fit together, and all the little nearly-invisible features that make some programs nice to use (auto-completion on fields, smart validation etc). This also helps with time estimation, since some of the previously-invisible tasks come to light. In my experience as a technical writer (which I alternate with Java SE & EE development) most user manuals are terribly written, far too pompous (since untrained developers often write them), and not written to be as simple as possible (K.I.S.S.!). They also often leak implementation details that confuse the user. No wonder users refuse to read them! My favourite style for technical writing is Information Mapping (seehttp://en.wikipedia.org/wiki/Information_mapping). It allows users to dip into places in a manual without having to read other parts of the manual first. This style tries to keep things very simple and is an excellent basis for training (which is where manuals really get used), and as a reference. It also provides a structure which is easy for the writer to follow, making the writing process less strenuous (the writer doesn't have to think about the structure, only the content). Once you've learned information mapping you can't imagine how to write technical documents without it. I recommend you give it a try if you have to write any formal documentation (software or otherwise).

by johnreynolds - 2008-09-08 09:41
"the user really couldn't tell you what they wanted because most of them had never used a GUI" I have great memories of user testing for DeskMate... The instructions said "Point the mouse at the button and click", so the participant picked up the mouse and pointed it at the button - like a TV remote control. Then there was the participant who didn't realize that she could pick up the mouse... she was moving the pointer down on the screen, and when she got to the edge of her desk she was stumped... The only way to move the mouse further in that direction was to drag it down the front of the desk - which she did :-) Ah... Glory days indeed! -JohnR

by tcowan - 2008-09-08 06:42
John, This was the entire focus of the agile movement starting in the late 90's, on site customer representative in the work room, etc. It's interesting that you harken back to the "glory" days, days in which the user really couldn't tell you what they wanted because most of them had never used a GUI...it was blue sky. The joy was in the creativity and freedom, and there were winners and loosers, but stil "glory days". Didn't Ford say something about if he were to give customers what they wanted he'd be giving them horse drawn buggies? (maybe that's a myth) I think we need to keep users somewhere in the middle, between a God like omnipotent declarer of what shall be and an idiot who we assume knows nothing...but definitely we need to include them in the software creation process as I find I cannot "put myself in their shoes" very well.

Taylor

by felipegaucho - 2008-09-08 06:35
it is beyond software.. IMHO, check your next TV or mobile phone.. none of the modern devices bother consumers with tons of useless details.. HP, Siemens and other giant manufacturers adopt ecology as the explanation why they don't release printed manuals anymore.. maximum a quick start guide and that's it.. you can download a huge PDF from the vendor web site if you want... :) It is nothing to do with software in my opinion.. it is a more general trend to simplicity.. what includes no thinking steps before of using a product :)

by johnreynolds - 2008-09-08 06:01
I feel your pain Felipe, It seems that software documentation can never keep pace with software development... I doubt that most of us even document our own code with meaningful javadoc so it's not really surprising that user documentation gets little respect. -JohnR

by felipegaucho - 2008-09-08 04:25
eheh, Hi John, I am following your Kafkanian conversion from developer to salesman, and I enjoy it because it helps me to think about each step..
Few years ago I was working on a traditional body shop TI company in Brazil and we was producing a software to a global wide reseller... and one of the release items we were supposed to produce was user's manual.. - after few months of hard programming working me and other code monkeys decided to produce the manual (to relax basically).. It would be distributed together of our software by one of the greatest IT companies in the world, so we all were excited in producing the best manual ever... and it came to several well formatted pages + pictures + diagrams, etc.. marketing & creativity exposed...
After few weeks, the US representative of our project visited us and did some motivational lecture to all developers team (btw, when you are working under body shop business model, the lack of good salary should be compensated by brilliant speeches). After some nice words about our cheap job, I mean, our good job, the representative didn't commented the manual, and me and my friends became curious about that.. The most brave monkey at that time (me I guess) had the courage to approximate the American boss to ask about that..
The answer was the unexpected: If the user is obligated to check the manual more than 1 or 2 times, the full software is crap.. so, our manuals are supposed to have a minimum number of pages, with some obvious pictures and big letters..
Today, thinking about my past life, I guess that boss was right.. manuals are for unexpected things.. complex details or custom usage of the software.. for the average features, it should be intuitive enough to the customer...