Writing a User Manual
-
-
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 -
-
And women can figure out how to start the application? :confused:
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 -
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.