Write The User Manual First
Write The User Manual FirstAn idea for an agile documenting strategy. This isn't even a ProtoPattern, as far as I know, lacking even a single example of use.
Topic titles WriteTheUserManualFirst and WriteTheUserManualFirstIsWaterfall aren't fitting the current discussion. There are other titles suggested for this page.
Context:
When a software project's deliverables must include a UserManual, administrator (or systems) manual, online help, (development documentation?), other artifacts not part of an executable image. (The project is delivered as a widely distributed shrink-wrapped product, for instance.) Since the customer needs a manual, our onus is to produce the best one we can. UserManual is interpreted here liberally. It doesn't require printed material, and it includes more than the instructions of how to press buttons in the application. But UserManual is a concise word for the concept.
Forces:
In an iteration, edit the UserManual before editing code. Use the manual as a guide for design and implementation in that iteration. Allow the details of the manual to adjust to technical realities found during development. In other words, write part of the UserManual first, and then you write code. Then correct the UserManual, if needed, and add more. Then repeat.
This should be iterative and incremental. A table of contents can be created early in the conceptualization of the product. The table of contents could serve as a high-level project view, showing what are reasonable subsystems and suggesting team assignments. As an outline is formed, prototypes and spikes can be created. When problems are discovered and changes in behavior have to be made, the UserManual is first changed to the new behavior, then it is implemented. About the same time as the product is completed, so is the manual.
This documentation process is done all the time informally. The boss or the architect or the supervisor asks what will the user do to perform such and such function. From the description itself they know if their approach is good or not and they adjust their algorithm accordingly. So they are sort of writing the manual as they go along. Why not keep the work?
Benefits:
MostApplicationsNeedaUserManual
This might be a way to effectively organize UserStorys into something that maintains long term value. Since the UserStorys are going to be released with the rest of the product we are motivated to reexamine them and make sure they reflect the current understanding of the product.
Writing a UserManual makes you view the software from the User's perspective. This helps us develop within the CustomerBillOfRights. After programming a project for a few months it is often the case that a developer knows the program far better than an average user. The developer considers a thing 'intuitive' and 'common sense' when in fact it's only familiar. Returning to the UserManual can help point out these misinterpretations.
Overly complex descriptions of features suggest overly complex features. If we find ourselves not being able to make a concise description of an intended feature, maybe the feature shouldn't be built that way.
Other Consequences:
Many people don't like maintaining documents. ProgrammersAreWriters, maybe, but are not always enthusiastic ones when it comes to human languages used by UserManuals. It means either adding a writer to a programming team or training (motivating) programmers to write, both approaches having drawbacks. Even if it doesn't make non-writing programmers better writers, it organizes the inputs to the writing stage in order to make the writer's job easier.
Probably a more practical process would be to integrate the ChangeLog with the UserManual. The manual could still be developed using an iterative process, documenting changes as they occurred. (Some changes would need no user documentation.) I've seen this documentation process used successfully, with a TechnicalWriter on the team who receives regular change updates from the developers.
I don't see the ChangeLog integration having the same motivating character as integrating the UserStory. ChangeLogs tell us what has been done to the program. A UserStory tells us what will be done. If the UserManual drives design, instead of the other way around, the UserManual stays closer to the truth.
Another approach is to develop the internal documentation and at the end use it as a basis for the end-user suite of documents.
The project is completed except for the user documentation. The project must wait, frozen, at the end for the documentation to be written. The forces don't allow for this.
A friend relates,
Holy Hand Grenade, Batman! I can't even add a signed entry and keep people from stepping all over the damn thing!! Nonetheless, here is an attempt to do so:
TestDrivenDesign insists on certain precision in ordering; why can't the user manual require the same level of precision as the tests? If I, as a customer, write or cause to be written a manual that describes in great detail the appearance of screens, the position and color of buttons, the noises produced, and the sequence of operations that some application or widget will contain then I expect my product to exactly match the manual. How then is the writing of the manual any different in concept than the writing of tests?
The point of having a manual, specification, or other written document that precisely describes the finished product is that I (the customer) have a fixed end result in mind before development work begins. As far as I am concerned there is no incremental development; there are no decisions to be made during development; there is no possibility of the product "working" in some manner other than the way I originally specified. I am unconcerned with modularity, reuse, or any other technical details. My only question is, can you produce this product exactly as I have specified within this time frame and for this budget? If you can't answer in the affirmative before such and such a date then I will take my project to the next development house. Maybe they can.
There is a specific kind of client -- albeit rare and wonderful -- who already knows what he wants and is unconcerned with how we provide that to him. This client has already written a user manual describing everything of any importance to him, so he expects the final result to exactly match that written document. Certainly not all clients are this hip. In fact, the vast bulk of them are clueless wonders who can't tell you what they want. They only know they don't want what you have already provided. However, if a client has invested the time, effort, and money required to create a fully fleshed-out user manual then they have their act pretty well together. We need to meet their requirements just as they are specified or risk being relegated to the dustbin of consulting. That's my story, and I'm sticking to it.
-- MartySchrader (signed to avoid various distortion)
"Write the user manual first" could be done either in either a sequential (i.e., waterfall) method or as a parallel (i.e., iterative) method. I, personally, lean towards a parallel model similar to TestFirstDesign. One could attempt to write all tests prior to writing a single line of code, but I doubt it would be effective. Likewise, one could attempt to write the final version of the user manual before writing a line of code, but again this would probably be an exercise in futility. What I would find useful in writing the user manual first is the marrying of business analysis, system design, and the user manual in an iterative approach. The users then have an existing business process that they follow (business analysis). The software needs to reflect this process flow (system design). The users need to be told how to use the software to support the business process (user manual). I also believe in keeping the user manual as light as possible. The better the user interface, the less the need for a written description, but reality often falls short of ideals. Some operations, especially rarely used ones, just may not be clear from the user interface. Perhaps in a couple more iterations, the users and developers will come up with a way to make it more clear, but for now, a user manual section -that shows for example how to handle delinquent accounts- may be invaluable.
Hmm. I once had a captive job at Dynapar Corp, ne. Danaher Controls, ne. Veeder-Root, blah blah blah. I think they call themselves Danaher these days. Anyway, these guys had been making 1/4 DIN and 1/2 DIN industrial process instruments since the dawn of creation. They had a new widget that they were working on when I was there where the user manual had been completely written and illustrated before the first line of 6800 assembly code was typed in. They knew from experience just exactly how they wanted this puppy to act, what buttons to push to make it act this way, and what the display would show with every button push. Everything. All of it.
Now, when the user manual is this clear, this exact, and this distinctive you can't argue with the product manager. "Gee, can we make it work this way?" "Heck no, we already have 15,000 manuals printed up for the first year's production. Just make it work like the book says." How do you change their mind about something like that?
It occurs to me that an iterative "Write the user manual first" approach ensures:
See: WriteTheUserManualFirstIsWaterfall, ShouldTheUserManualBeAgile, UserManualIsNotUserStory, UserManualIsAntiPattern, UserManualIsAnAntiPattern, LineByLineReview, DocumentsFirstCodeLater, DocumentLast, ReplaceDocumentation, ExtremeDocumentation, ExtremeDocuments, UserDocsInXp
Contributors: SkipSailors, TimKing, DougMerritt, TomStambaugh, MartySchrader
EditText of this page
(last edited April 2, 2014)
or FindPage with title or text search