No matter what type of project you're working on, you can't expect users to fully understand it on their own. That's where documentation comes in. Docs can be anything from simple procedures to thorough user stories. Sure, a web UI can sometimes speak for itself (and the best ones do), but I'm sure you've seen tales of readers questioning basic UI paths or squirming about doing anything on the command line.
This is why creating documentation—even for the most basic of topics—is important for users.
If you want more proof, let's talk about Goofy. The loveable star of Goof Troop, Kingdom Hearts, and numerous Disney shorts, Goofy is the definition of the "basic user." He tries his hardest and, even though he has a lot of problems, he somehow always manages to fail up. One reason for his troubles may be the poor quality of the documentation he uses. Much of it is problematic and directly leads to failure, confusion, and even personal harm. This is what happens in the great Goofy short How to Fish.
How to Fish, copyright, Disney, 1942.
The good news is How to Fish is a great example of why good documentation is so important (and why bad documentation is such a problem). Let's go through the short video and look at some of the ways poor documentation for this seemingly simple task causes Goofy so many problems. I'll also share my advice on how to improve it.
Goofy wants to learn to fish, a task some of us think is very easy. But sometimes the most basic users (like Goofy) want to start at the beginning, thus the relevance of a book like How to Fish.
00:40
We're getting a lot of backstory on how the Earth's tides and bodies of water work. Is this necessary? I'd delete the parts about Neptune and cosmic vibrations. Perhaps this section should reference material on the best time to fish for the best results.
01:20
The reader of How to Fish already has the desire to fish. He does not need to be told why he desires to fish. I'd delete this.
01:35
Is "fishing fever" an established term? The word "fever" has negative connotations. If this is your original concept, perhaps choose a friendlier term, such as "fishing enthusiasm." Or maybe keep it simple and stick with "the desire to fish." Perhaps "a favor for fishing," if you want to keep the alliteration.
01:45
In the video, Goofy is shown testing his fishing equipment, but at no point is the necessary fishing equipment listed in the documentation. This is important and should be highlighted in a prerequisites section.
Prerequisites:
- Fishing pole
- Lure
01:50
This quick intro to casting motions is helpful, but should there be more information? Is this going to be outlined somewhere in the future?
Also, I'd include a troubleshooting admonition:
WARNING: Do not fish indoors. Could lead to attracting the wrong fish and increased risk for head injuries.
02:00
Re: "The angler can easily imagine a fighting fish in a crystal pool." This statement is very vague. It's my understanding that fighting fish are native to Southeast Asia. Is the reader of this guide expected to be fishing in Southeast Asia? Please define "a crystal pool."
02:08
This section is titled "Where to fish," but only one location is mentioned (a "high, rugged mountain," an unlikely habitat for fish, which live in water) and only in reference to the "feel" of the environment. This could be summarized better with something like the following:
Where to fish:
- Mountain river or stream
02:40
This section of the video alludes to equipment needed for a camping/fishing trip. Should there be a list of what to pack for a fishing trip to the mountain? See my comment above about listing the necessary equipment in a prerequisite.
02:50
The trout's features are described here. Is this necessary to knowing how to catch trout? Is trout the only type of fish the documentation covers? If so, should the title be changed to: "How to fish for trout"? Should the documentation be expanded to include other fish?
03:20
Should there be an admonition here? For example:
Be sure to sneak quietly and look where you're going, otherwise, you may fall down a mountain and lose your clothes in a tree.
04:00
We would benefit from more context about fly fishing and the reasons it causes fish to laugh at fisherman.
04:25
In the section on lures, Goofy moves a single string to make the lure do a complex dance. Can you provide more information about how this works? Does the style of music matter? If so, perhaps a table with information on the different types of music and the effects they have on the fish would be necessary.
04:40
It might be good to add another admonition:
WARNING: When tempting fish with the dancing lure, make sure not to back over a rock in the stream. This can lead to personal harm and loss of previously caught fish.
04:55
This explanation of casting would be much better if it were placed higher in the documentation. Perhaps around the 03:20 mark, when fishing is first explained.
Would there be benefits in explaining the different casting methods with different types of fishing (e.g., fly, lure, worm, etc.)? This would work well in a comparison table.
05:02
While the documentation seems to accurately explain the proper arm movement to achieve a "perfect cast" (as described at 05:36), Goofy's cast is partially successful, in that his line "zings," but he does not reel in a fish. Are there additional details that would help him avoid casting his line into a tree?
05:50
The documentation differentiates here between lake fishing and other types of fishing. Would it be best to change the section above to "River fishing"? Also, for lake fishing, do we need a separate prerequisites section?
Prerequisites:
- Boat
06:04
Goofy hooks his boat motor. Would an admonition about boat motors help?
WARNING: Don't have the reel cast when in a moving boat. This can cause the line to be caught in the rotating motor blades and lead you to mistakenly think you've caught a big fish. Instead, this can lead to loss of your boat engine and your boat, due to it being cut into multiple pieces by the motor blades. If you accidentally hook your motor, simply let go of the fishing rod, otherwise, the motor will carry you through the water and you may hit your head on a tree.
06:15
This part of the documentation includes some good tips about what to do when a fish (or boat motor?) is hooked, but they are rattled off in a different voice. Can these be listed in a more suitable way?
Some other thoughts:
- At 01:35, Goofy flies through the air, presumably a symptom of the "fishing fever" (as you call it). I think this skill would be beneficial to the reader in other parts of the instructions, especially around 05:30 when he flies through the air due to incorrect casting procedure. Which flight methodology is correct? Does fishing fever cause flight?
- I'm quite worried that the procedures shown in this guide will not, in fact, lead to a successful fishing experience. The only fish that appeared to have been caught were accidentally let go when Goofy tripped over a rock. Also, the documentation does not indicate how the fish were caught in the first place. In the end, Goofy ends up with a motor instead of any fish. If that was its purpose, perhaps this guide should be renamed to "How to go fishing, but catch a boat engine instead."
Now that Goofy's plight has helped us realize some common documentation pitfalls, I'm curious: Do you have any other tips for helping to write better documentation for the basic user? Could it be as simple as "write for every type of user?" Feel free to share your thoughts in the comments.
2 Comments