Writing a User Manual
-
MehGerbil wrote:
nobody is ever going to read.
I normally write the first & last pages, then copy & paste Greek news articles into all the other pages in between. Still, when end users call for support, they insist they have read the manual.
"Coming soon"
-
TPFKAPB wrote:
Real men don't read manuals.
..ever since the introduction of the word "discoverability", and the omission of a user-manual with Windows, I've been working under the idea that software-interfaces should be predictable, self-explanatory and intuitive. A manual that says "click here to do X" does not really help much. A reference OTOH.. FWIW, you're implying that a programmer cannot be a real man :)
Bastard Programmer from Hell :suss: if you can't read my code, try converting it here[^]
-
I hate that, it's the part I think all developers hate and most, including myself are not very good at.
VS2010/Atmel Studio 6.0 ToDo Manager Extension
Version 3.0 now available. There is no place like 127.0.0.1 -
Try incorporating some nonsense statements and see if anybody notices... :-D "Click the Fubar button in the lower right corner. Then paint the horse yellow and fly away to the moon! If that doesn't work, please contact the [Insert company name here] helpdesk."
Why can't I be applicable like John? - Me, April 2011
-----
Beidh ceol, caint agus craic againn - Seán Bán Breathnach
-----
Da mihi sis crustum Etruscum cum omnibus in eo!
-----
Just because a thing is new don’t mean that it’s better - Will Rogers, September 4, 1932 -
Eddy Vluggen wrote:
What makes you so sure on that?
Because the questions I get indicate that they've never read anything outside of a TV Guide, much less the user manual I provided. I work with people who lose a file every time the default location in Windows Explorer changes. They just save the file to whatever default location comes up - so if that default location changes for any reason they lose files. Me: So where did you save the file? Them: eh? Me: What location did you save the file - where did you choose to save it? Them: Same place I always save it. Me: So you selected to save it at C:\Users\moron\porn\dungeon\farmanimals Them: I didn't select a folder. Me: What was the file name, I'll just do a search on your harddrive. Them: eh? Me: Here is a rubber ball. Go play with it out in the parking lot.
-
Then your manual sucks. "Clicking the print button prints the current document or selection." Yeah baby, tell me.
-
Eddy Vluggen wrote:
What makes you so sure on that?
Because the questions I get indicate that they've never read anything outside of a TV Guide, much less the user manual I provided. I work with people who lose a file every time the default location in Windows Explorer changes. They just save the file to whatever default location comes up - so if that default location changes for any reason they lose files. Me: So where did you save the file? Them: eh? Me: What location did you save the file - where did you choose to save it? Them: Same place I always save it. Me: So you selected to save it at C:\Users\moron\porn\dungeon\farmanimals Them: I didn't select a folder. Me: What was the file name, I'll just do a search on your harddrive. Them: eh? Me: Here is a rubber ball. Go play with it out in the parking lot.
I always offer some way option to show the just-saved file in windows explorer. When this is some kind of "export", I even default to doing this automatically. And yes, for internal tools this option is labeled "Where did I save this?"
-
I always offer some way option to show the just-saved file in windows explorer. When this is some kind of "export", I even default to doing this automatically. And yes, for internal tools this option is labeled "Where did I save this?"
-
Eddy Vluggen wrote:
What makes you so sure on that?
Because the questions I get indicate that they've never read anything outside of a TV Guide, much less the user manual I provided. I work with people who lose a file every time the default location in Windows Explorer changes. They just save the file to whatever default location comes up - so if that default location changes for any reason they lose files. Me: So where did you save the file? Them: eh? Me: What location did you save the file - where did you choose to save it? Them: Same place I always save it. Me: So you selected to save it at C:\Users\moron\porn\dungeon\farmanimals Them: I didn't select a folder. Me: What was the file name, I'll just do a search on your harddrive. Them: eh? Me: Here is a rubber ball. Go play with it out in the parking lot.
MehGerbil wrote:
I work with people who lose a file every time the default location in Windows Explorer changes. They just save the file to whatever default location comes up - so if that default location changes for any reason they lose files.
You're not updating the entries in the "Recent File List"? There's a "documents" section in the start-menu :) No, still wouldn't be any help to the type of user you describe; someone who isn't interested in what he/she is doing, cannot be helped. It'd be a prayer without end, and I'd be supporting MS-Word related problems in no time - explaining what a 'document' is, isn't my job. We got cheap books that explain those idea's. KISS. You don't need an engineer to personally explain what a file-path is. And you're right - if they don't read books, they'll probably skip the personalized manual in the same way.
Bastard Programmer from Hell :suss: if you can't read my code, try converting it here[^]
-
If you every write a technical manual that contains a fault finding table or a flowchart, make sure to add a cure such as "Apply liberal sprinkling of Pixie Dust". :)
Dave Find Me On: Web|Facebook|Twitter|LinkedIn
Folding Stats: Team CodeProject
-
It depends on the type of manual, how it will be delivered/maintained and the audience it will have. The pages for the manual I wrote for Visual Lint[^] are among the busiest on our website, so the many hours I put into working on it (valuable coding time!) have definitely been worthwhile. I am of the opinion that being able to write good technical content is an essential skill for a software developer, so even if the content is not going to be particularly useful to anyone you can look at it as a useful training exercise.
Anna :rose: Tech Blog | Visual Lint "Why would anyone prefer to wield a weapon that takes both hands at once, when they could use a lighter (and obviously superior) weapon that allows you to wield multiple ones at a time, and thus supports multi-paradigm carnage?"
-
Why, then, is it called _man_ual? ;)
-
It depends on the type of manual, how it will be delivered/maintained and the audience it will have. The pages for the manual I wrote for Visual Lint[^] are among the busiest on our website, so the many hours I put into working on it (valuable coding time!) have definitely been worthwhile. I am of the opinion that being able to write good technical content is an essential skill for a software developer, so even if the content is not going to be particularly useful to anyone you can look at it as a useful training exercise.
Anna :rose: Tech Blog | Visual Lint "Why would anyone prefer to wield a weapon that takes both hands at once, when they could use a lighter (and obviously superior) weapon that allows you to wield multiple ones at a time, and thus supports multi-paradigm carnage?"
I agree absolutely, unfortunately a skill many of us fail to learn.
-
If its difficult to understand for a typical (uninformed) user, then yes, it won't be read. The point of a manual is aid the user, and this aid has to be more helpful and require less work than calling support. If you cannot deliver that, then yes, the effort is wasted. I've seen lots of cases where manuals assume 'basic' knowledge that the developers of the application take for granted, but a user may not have. This may even include knowledge about internally used algorithms and data structures. Also, even a very good explanation of a complicated thing may be hard to grasp if it isn't also illustrated well, preferably with a real-world example. A text-only explanation with a trivial example that has nothing to do with real-world problems won't help half as much. As for locating the manual (mentioned further down in the thread) - why does that have to be a problem? Install it with your program and provide a button or link to it right within your application. If many users use your application, then a good manual can save you and your support a whole lot of work.
-
TPFKAPB wrote:
Real men don't read manuals.
..ever since the introduction of the word "discoverability", and the omission of a user-manual with Windows, I've been working under the idea that software-interfaces should be predictable, self-explanatory and intuitive. A manual that says "click here to do X" does not really help much. A reference OTOH.. FWIW, you're implying that a programmer cannot be a real man :)
Bastard Programmer from Hell :suss: if you can't read my code, try converting it here[^]
How long before the next airliner comes without manuals? Just two big buttons in the cockpit labelled "up" and "down". Then again, it seems even real aircraft engineers don't read manuals:
"Enter the Arab flight crew of Abu Dhabi Aircraft Technologies (ADAT) to conduct pre-delivery tests on the ground, such as engine run-ups prior to delivery to Etihad Airways in Abu Dhabi ... The ADAT crew taxied the A340-600 to the run-up area. Then they took all four engines to takeoff power with a virtually empty aircraft. Not having read the run-up manuals, they had no clue just how light an empty A340-600 really is. The takeoff warning horn was blaring away in the cockpit because they had all 4 engines at full power. The aircraft computers thought they were trying to take off, but it had not been configured properly (flaps/slats, etc..) Then one of the ADAT crew decided to pull the circuit breaker on the Ground Proximity Sensor to silence the alarm. This fools the aircraft into thinking it is in the air. The computers automatically released all the brakes and set the aircraft rocketing forward. The ADAT crew had no idea that this is a safety feature so that pilots can't land with the brakes on. Not one member of the seven-man Arab crew was smart enough to throttle back the engines from their max power setting, so the $200 million brand-new aircraft crashed into a blast barrier, totaling it."
The above is the "urban myth" version of the story. What is supposed to actually have happened is that no-one thought to chock the wheels prior to a full engine run-up. The brakes aren't powerful enough to hold against full engine thrust so the plane moved forward. "Surprise led the ground-test technician to focus on the braking system, so he did not think about reducing the engines' thrust," and the problem was supposedly compounded by the attempts to steer away from the wall, which decreased hydraulic pressure on the braking system, effectively releasing the brakes. [I for one find it hard to comprehend that in a $200M airbus, the nosewheel steering system and the braking system share a single hydraulic circuit...???] Whichever version of the story you choose to believe, a little more attention to the manual before the tests started might have been beneficial...
-
How long before the next airliner comes without manuals? Just two big buttons in the cockpit labelled "up" and "down". Then again, it seems even real aircraft engineers don't read manuals:
"Enter the Arab flight crew of Abu Dhabi Aircraft Technologies (ADAT) to conduct pre-delivery tests on the ground, such as engine run-ups prior to delivery to Etihad Airways in Abu Dhabi ... The ADAT crew taxied the A340-600 to the run-up area. Then they took all four engines to takeoff power with a virtually empty aircraft. Not having read the run-up manuals, they had no clue just how light an empty A340-600 really is. The takeoff warning horn was blaring away in the cockpit because they had all 4 engines at full power. The aircraft computers thought they were trying to take off, but it had not been configured properly (flaps/slats, etc..) Then one of the ADAT crew decided to pull the circuit breaker on the Ground Proximity Sensor to silence the alarm. This fools the aircraft into thinking it is in the air. The computers automatically released all the brakes and set the aircraft rocketing forward. The ADAT crew had no idea that this is a safety feature so that pilots can't land with the brakes on. Not one member of the seven-man Arab crew was smart enough to throttle back the engines from their max power setting, so the $200 million brand-new aircraft crashed into a blast barrier, totaling it."
The above is the "urban myth" version of the story. What is supposed to actually have happened is that no-one thought to chock the wheels prior to a full engine run-up. The brakes aren't powerful enough to hold against full engine thrust so the plane moved forward. "Surprise led the ground-test technician to focus on the braking system, so he did not think about reducing the engines' thrust," and the problem was supposedly compounded by the attempts to steer away from the wall, which decreased hydraulic pressure on the braking system, effectively releasing the brakes. [I for one find it hard to comprehend that in a $200M airbus, the nosewheel steering system and the braking system share a single hydraulic circuit...???] Whichever version of the story you choose to believe, a little more attention to the manual before the tests started might have been beneficial...
-
I understand your point; however, I think it's a bad example. I'd like to think the guy flying a plane I'm in has done quite a bit more than read the manual.
-
I agree absolutely, unfortunately a skill many of us fail to learn.
Unfortunate indeed.
Anna :rose: Tech Blog | Visual Lint "Why would anyone prefer to wield a weapon that takes both hands at once, when they could use a lighter (and obviously superior) weapon that allows you to wield multiple ones at a time, and thus supports multi-paradigm carnage?"
-
You're lucky your application requires only several days of work for an user manual.
To alcohol! The cause of, and solution to, all of life's problems - Homer Simpson ---- Our heads are round so our thoughts can change direction - Francis Picabia