Write The User Manual As You Go

It is one of several approaches to UserManuals:

• Write the user manual as you go.
• WriteTheUserManualFirst
  • as the first step in each iteration.
  • or as an early step in a WaterFall process.
• Write the user manual last.
• Let Professional TechnicalWriters write the manual when the software is done.
  • The technical writer who believes this is possible has no experience. Is the company going to wait for several months after all programming work is done for the manual to be written? See UserDocsInXp.
• Don't write a user's manual, write a Frequently Asked Questions instead.
• Don't worry about user manuals at all, assume the software is so easy to use that they can use the product intuitively.

---

If the iterations are short enough, there is very little difference between writing the user manual "as you go", "as the first step in each iteration", and "as the last step in each iteration".

---

In those rare and wonderful cases where the customer actually knows what they want to do long before the development process begins then the user manual could be written before the first board is etched or the first line of code is compiled. I did a captive stint at a firm that created completed user manuals for products that were totally vapor, then set the engineering staff to the effort of making a product that worked exactly like the manual said. 15,000 manuals printed up beforehand kinda makes one think twice about trying to change a feature on the fly, y'know?

• Hilarious! Was it a 100 page manual with a 200 page errata? In my experience, documentation written before the software (including specifications) ends up including a fair amount of logical contradictions and even violations of mathematics and the laws of physics. The software is like the documentation's UnitTest. And we all know what happens to stuff without tests... -- IanOsgood

I'm glad you are so easily entertained, Ian. In your experience, indeed. You are simply revealing how limited your experience is when you make blanket statements like that.

The firm in question had been in the controls business for twenty years and was considered the Cadillac of the industry. They had put hundreds of successful products on the market and had made dozens of controls similar to the model in mind. These guys had Worked Out A System for presenting information to the user and getting his inputs. The (very sizable) user base really didn't want "improvements" to the UI if it meant making changes to the way they conducted their own business.

Therefore, the user manual represented all that the instrument was supposed to do and exactly how the user should go about doing it. With that in mind I simply built the durn thing the way I was told.

As for testing, I have been writing on this Wiki for a decade about testing versus inspection. I'm not going to get dragged into that argument again here. If you are interested you can look around for more on QFD, Fagan, etc. Up to you. -- MartySchrader

---

CategorySoftwareTool, CategoryDocumentation