Discussion:
Dilbert: Tina Enters Coma
Add Reply
Lynn McGuire
2019-12-02 18:44:29 UTC
Reply
Permalink
Dilbert: Tina Enters Coma
https://dilbert.com/strip/2019-12-02

Tech writing is not easy, but the tech writers need to make it easy for
the users.

Lynn
Dorothy J Heydt
2019-12-02 19:06:42 UTC
Reply
Permalink
Post by Lynn McGuire
Dilbert: Tina Enters Coma
https://dilbert.com/strip/2019-12-02
Tech writing is not easy, but the tech writers need to make it easy for
the users.
Or, as has been often said, "Don't tell me to RTFM if you WTFM!"
--
Dorothy J. Heydt
Vallejo, California
djheydt at gmail dot com
www.kithrup.com/~djheydt/
Ted Nolan <tednolan>
2019-12-02 19:22:07 UTC
Reply
Permalink
Post by Dorothy J Heydt
Post by Lynn McGuire
Dilbert: Tina Enters Coma
https://dilbert.com/strip/2019-12-02
Tech writing is not easy, but the tech writers need to make it easy for
the users.
Or, as has been often said, "Don't tell me to RTFM if you WTFM!"
Tina Enters Comma..
--
columbiaclosings.com
What's not in Columbia anymore..
Robert Carnegie
2019-12-02 21:34:17 UTC
Reply
Permalink
Post by Ted Nolan <tednolan>
Post by Dorothy J Heydt
Post by Lynn McGuire
Dilbert: Tina Enters Coma
https://dilbert.com/strip/2019-12-02
Tech writing is not easy, but the tech writers need to make it easy for
the users.
Or, as has been often said, "Don't tell me to RTFM if you WTFM!"
But I WTFM so that you could RTFM.

Hmm, not always true; today I performed a couple of
processes, one of which I WTFM so that /I/ can RTFM
and remind myself how to do it - in theory, someone else
could, but it's always me - and another, I rewrote about
half of TFM for the process as it now stands, then put off
finishing because, again, it's always me doing it.
I've recommended that someone else should get a turn,
and if that ever happens then between us we can discuss
and document the job. There are probably steps completely
obvious to me that need very detailed explanation, and
you find that out by trying.
Post by Ted Nolan <tednolan>
Tina Enters Comma..
--
columbiaclosings.com
What's not in Columbia anymore..
,

...and then what?
Paul S Person
2019-12-03 17:44:16 UTC
Reply
Permalink
On Mon, 2 Dec 2019 13:34:17 -0800 (PST), Robert Carnegie
Post by Robert Carnegie
Post by Ted Nolan <tednolan>
Post by Dorothy J Heydt
Post by Lynn McGuire
Dilbert: Tina Enters Coma
https://dilbert.com/strip/2019-12-02
Tech writing is not easy, but the tech writers need to make it easy for
the users.
Or, as has been often said, "Don't tell me to RTFM if you WTFM!"
But I WTFM so that you could RTFM.
Hmm, not always true; today I performed a couple of
processes, one of which I WTFM so that /I/ can RTFM
and remind myself how to do it - in theory, someone else
could, but it's always me - and another, I rewrote about
half of TFM for the process as it now stands, then put off
finishing because, again, it's always me doing it.
I've recommended that someone else should get a turn,
and if that ever happens then between us we can discuss
and document the job. There are probably steps completely
obvious to me that need very detailed explanation, and
you find that out by trying.
Post by Ted Nolan <tednolan>
Tina Enters Comma..
,
...and then what?
That is exactly what they are debating today (just push the right-side
arrow on the link above.

After reading many manuals, my conclusion is that they fail for
several reasons:

1. If they are written /first/, there is no guarantee the
device/program will work as described. For one thing, the initial
description often turns out to be surprisingly ... vague ... as the
process continues.

2. If they are written by a /novice/, there is no guarantee that the
information will be correct, because a novice doesn't know the
device/program. OTOH, a novice's experiences learning the program can
make a fine tutorial.

3. If they are written by an /expert/, they will generally be
unintelligible, because what is obvious to the expert is gobbledegook
to the rest of us.

The most useful manuals are those produced by experts, not because you
can learn how to /use/ the device/program, but because, once you have
figured it out for yourself, they make /excellent/ reference
documents. IOW, once you get to the point where you have sufficiently
specific questions, you can generally find the answers if an expert
wrote the manual.

There were several occasions where, having specific questions, I went
to a local bookstore and browed the shelves, examining the /indexes/
to see which books had /answers/. If a book had the answers to all my
questions, I bought, on the grounds that it would probably have many
more answers that I would find helpful in the future.
--
"I begin to envy Petronius."
"I have envied him long since."
Joe Pfeiffer
2019-12-03 18:35:35 UTC
Reply
Permalink
Post by Paul S Person
After reading many manuals, my conclusion is that they fail for
1. If they are written /first/, there is no guarantee the
device/program will work as described. For one thing, the initial
description often turns out to be surprisingly ... vague ... as the
process continues.
2. If they are written by a /novice/, there is no guarantee that the
information will be correct, because a novice doesn't know the
device/program. OTOH, a novice's experiences learning the program can
make a fine tutorial.
3. If they are written by an /expert/, they will generally be
unintelligible, because what is obvious to the expert is gobbledegook
to the rest of us.
The most useful manuals are those produced by experts, not because you
can learn how to /use/ the device/program, but because, once you have
figured it out for yourself, they make /excellent/ reference
documents. IOW, once you get to the point where you have sufficiently
specific questions, you can generally find the answers if an expert
wrote the manual.
There were several occasions where, having specific questions, I went
to a local bookstore and browed the shelves, examining the /indexes/
to see which books had /answers/. If a book had the answers to all my
questions, I bought, on the grounds that it would probably have many
more answers that I would find helpful in the future.
You've made a very important distinction here, which I think is too
often forgotten: tutorials (and textbooks) serve a different purpose
than manuals, serve a different audience, and need a different
approach.

I don't know how many times I've seen complaints about manuals that take
the general form "I couldn't figure out how to use the <whatever> from
the manual". You're not supposed to be able to... the manual is for
after you've learned how to do it and need information about the fine
points.

Years ago, as I was learning to use the FUSE filesystem library, I found
the documentation so incomprehensible I wound up taking very careful
notes. Once I tidied up those notes I put them on line at
https://www.cs.nmsu.edu/~pfeiffer/fuse-tutorial/

A google search for "fuse filesystem tutorial" turns this up as the
first hit. Every so often I get an email from someone thanking me
(and/or asking questions, which sometimes turn into a revision of the
tutorial).
Quadibloc
2019-12-04 03:36:46 UTC
Reply
Permalink
Post by Joe Pfeiffer
I don't know how many times I've seen complaints about manuals that take
the general form "I couldn't figure out how to use the <whatever> from
the manual". You're not supposed to be able to... the manual is for
after you've learned how to do it and need information about the fine
points.
A manual is not a reference encyclopedia. It indeed is supposed to be a book
that tells you, step by step, exactly how to use the product to produce the
expected results.

At least in general. That is what the manual for a car, a refrigerator, a TV
set, or an automatic rifle would be: the book that comes with it, and lets you
use it.

Software products, however, tend to be more complicated. These products are
often open-ended in what you can do with them. So the manual can't provide a
tutorial for every possible thing you could do with the product, as such a
manual might not fit on the whole planet.

Even in perhaps the worst case - the manual for a compiler, say - what it should
do is say: here is how you build an application with windows and a menu and push
buttons... and then goes into reference mode for the different computations and
functions you might want to put in that application.

Ideally, a manual should be a joint effort between people at different levels of
expertise, to ensure the finished product will actually serve its intended
purpose fully, by being accurate, complete, _and_ accessible.

I know that setting this uncompromising standard may seem like asking for the
impossible, but if we forget what our goal should be, we're sure not to make
progress towards it.

John Savard
Gary R. Schmidt
2019-12-04 12:40:37 UTC
Reply
Permalink
Post by Quadibloc
Post by Joe Pfeiffer
I don't know how many times I've seen complaints about manuals that take
the general form "I couldn't figure out how to use the <whatever> from
the manual". You're not supposed to be able to... the manual is for
after you've learned how to do it and need information about the fine
points.
A manual is not a reference encyclopedia. It indeed is supposed to be a book
that tells you, step by step, exactly how to use the product to produce the
expected results.
Not if it's produced for a CA product, in which case it is intended as
so much wordage that the luser
VP/MD/insert-appropriate-level-of-cluelessness will be convinced that it
does everything the salesdroid says it does, and that the overworked
coal-facing manager/admin/person-who-knows-what-is-going-on[1] will not
have time to work out that it *doesn't* before the luser has bought
ludicrous-number-of-licenses-for-said-product.

Cheers,
Gary B-)

1 - Not that the person who *really* knows how things work, the bosses
PA/secretary/receptionist will get a chance at it, she's too busy
keeping the plates spinning as it is.
--
When men talk to their friends, they insult each other.
They don't really mean it.
When women talk to their friends, they compliment each other.
They don't mean it either.
Paul S Person
2019-12-04 17:43:18 UTC
Reply
Permalink
Post by Quadibloc
Post by Joe Pfeiffer
I don't know how many times I've seen complaints about manuals that take
the general form "I couldn't figure out how to use the <whatever> from
the manual". You're not supposed to be able to... the manual is for
after you've learned how to do it and need information about the fine
points.
A manual is not a reference encyclopedia. It indeed is supposed to be a book
that tells you, step by step, exactly how to use the product to produce the
expected results.
At least in general. That is what the manual for a car, a refrigerator, a TV
set, or an automatic rifle would be: the book that comes with it, and lets you
use it.
I've seen /some/ manuals, no doubt translated from another language by
someone doing his or her inadequate best, that might serve as
counterexamples.

But, yes, if I imagine a manual for such things written like the
manual I have for the make utility of a compiler I use, nobody would
/ever/ be able to use /any/ of those objects except by
trial-and-error.

Which is /not/ the way to learn how to use an automobile or a rifle!
Post by Quadibloc
Software products, however, tend to be more complicated. These products are
often open-ended in what you can do with them. So the manual can't provide a
tutorial for every possible thing you could do with the product, as such a
manual might not fit on the whole planet.
They still have limits. The manual for a word processor does /not/
have to discuss how a spreadsheet works.

Or, at least, didn't until office suites came into use.
Post by Quadibloc
Even in perhaps the worst case - the manual for a compiler, say - what it should
do is say: here is how you build an application with windows and a menu and push
buttons... and then goes into reference mode for the different computations and
functions you might want to put in that application.
That makes sense, and the most usuable manuals do that.

Indeed, I would say you are mixing three different manuals: one for
using the /compiler/, which is about command-line options, one for the
language itself, covering such topics as character sets and operator
precedence and syntax errors, and one for the inevitable library,
covering all those wierd functions that look as if they ought to do
something, and which do, indeed, do something, just not necessarily
what a sane person might expect.
Post by Quadibloc
Ideally, a manual should be a joint effort between people at different levels of
expertise, to ensure the finished product will actually serve its intended
purpose fully, by being accurate, complete, _and_ accessible.
I know that setting this uncompromising standard may seem like asking for the
impossible, but if we forget what our goal should be, we're sure not to make
progress towards it.
Actually, a better pattern, in many ways, is a help file linked to the
program. Contex-sensitive help, avoiding the minor problem of how the
user will actually /find/ information on a topic when he or she may
not know the technical terms in which the topic is defined.
--
"I begin to envy Petronius."
"I have envied him long since."
Dimensional Traveler
2019-12-04 19:12:27 UTC
Reply
Permalink
Post by Paul S Person
Post by Quadibloc
Post by Joe Pfeiffer
I don't know how many times I've seen complaints about manuals that take
the general form "I couldn't figure out how to use the <whatever> from
the manual". You're not supposed to be able to... the manual is for
after you've learned how to do it and need information about the fine
points.
A manual is not a reference encyclopedia. It indeed is supposed to be a book
that tells you, step by step, exactly how to use the product to produce the
expected results.
At least in general. That is what the manual for a car, a refrigerator, a TV
set, or an automatic rifle would be: the book that comes with it, and lets you
use it.
I've seen /some/ manuals, no doubt translated from another language by
someone doing his or her inadequate best, that might serve as
counterexamples.
But, yes, if I imagine a manual for such things written like the
manual I have for the make utility of a compiler I use, nobody would
/ever/ be able to use /any/ of those objects except by
trial-and-error.
Which is /not/ the way to learn how to use an automobile or a rifle!
Post by Quadibloc
Software products, however, tend to be more complicated. These products are
often open-ended in what you can do with them. So the manual can't provide a
tutorial for every possible thing you could do with the product, as such a
manual might not fit on the whole planet.
They still have limits. The manual for a word processor does /not/
have to discuss how a spreadsheet works.
Or, at least, didn't until office suites came into use.
Post by Quadibloc
Even in perhaps the worst case - the manual for a compiler, say - what it should
do is say: here is how you build an application with windows and a menu and push
buttons... and then goes into reference mode for the different computations and
functions you might want to put in that application.
That makes sense, and the most usuable manuals do that.
Indeed, I would say you are mixing three different manuals: one for
using the /compiler/, which is about command-line options, one for the
language itself, covering such topics as character sets and operator
precedence and syntax errors, and one for the inevitable library,
covering all those wierd functions that look as if they ought to do
something, and which do, indeed, do something, just not necessarily
what a sane person might expect.
Post by Quadibloc
Ideally, a manual should be a joint effort between people at different levels of
expertise, to ensure the finished product will actually serve its intended
purpose fully, by being accurate, complete, _and_ accessible.
I know that setting this uncompromising standard may seem like asking for the
impossible, but if we forget what our goal should be, we're sure not to make
progress towards it.
Actually, a better pattern, in many ways, is a help file linked to the
program. Contex-sensitive help, avoiding the minor problem of how the
user will actually /find/ information on a topic when he or she may
not know the technical terms in which the topic is defined.
Will it include a manual for the context-sensitive program?
--
"You need to believe in things that aren't true. How else can they become?"
Paul S Person
2019-12-05 18:14:19 UTC
Reply
Permalink
On Wed, 4 Dec 2019 11:12:27 -0800, Dimensional Traveler
Post by Dimensional Traveler
Post by Paul S Person
Post by Quadibloc
Post by Joe Pfeiffer
I don't know how many times I've seen complaints about manuals that take
the general form "I couldn't figure out how to use the <whatever> from
the manual". You're not supposed to be able to... the manual is for
after you've learned how to do it and need information about the fine
points.
A manual is not a reference encyclopedia. It indeed is supposed to be a book
that tells you, step by step, exactly how to use the product to produce the
expected results.
At least in general. That is what the manual for a car, a refrigerator, a TV
set, or an automatic rifle would be: the book that comes with it, and lets you
use it.
I've seen /some/ manuals, no doubt translated from another language by
someone doing his or her inadequate best, that might serve as
counterexamples.
But, yes, if I imagine a manual for such things written like the
manual I have for the make utility of a compiler I use, nobody would
/ever/ be able to use /any/ of those objects except by
trial-and-error.
Which is /not/ the way to learn how to use an automobile or a rifle!
Post by Quadibloc
Software products, however, tend to be more complicated. These products are
often open-ended in what you can do with them. So the manual can't provide a
tutorial for every possible thing you could do with the product, as such a
manual might not fit on the whole planet.
They still have limits. The manual for a word processor does /not/
have to discuss how a spreadsheet works.
Or, at least, didn't until office suites came into use.
Post by Quadibloc
Even in perhaps the worst case - the manual for a compiler, say - what it should
do is say: here is how you build an application with windows and a menu and push
buttons... and then goes into reference mode for the different computations and
functions you might want to put in that application.
That makes sense, and the most usuable manuals do that.
Indeed, I would say you are mixing three different manuals: one for
using the /compiler/, which is about command-line options, one for the
language itself, covering such topics as character sets and operator
precedence and syntax errors, and one for the inevitable library,
covering all those wierd functions that look as if they ought to do
something, and which do, indeed, do something, just not necessarily
what a sane person might expect.
Post by Quadibloc
Ideally, a manual should be a joint effort between people at different levels of
expertise, to ensure the finished product will actually serve its intended
purpose fully, by being accurate, complete, _and_ accessible.
I know that setting this uncompromising standard may seem like asking for the
impossible, but if we forget what our goal should be, we're sure not to make
progress towards it.
Actually, a better pattern, in many ways, is a help file linked to the
program. Contex-sensitive help, avoiding the minor problem of how the
user will actually /find/ information on a topic when he or she may
not know the technical terms in which the topic is defined.
Will it include a manual for the context-sensitive program?
Actually, most of the software I have gotten over the last decade or
two has /not/ had a printed manual -- but most of them had help files,
in some cases accessible independently of the program.

Hardware often comes with a booklet, but, more and more, these tend to
be "quick setup" booklets which turn out to be even skimpier than they
look because they are printed in multiple languages. Online PDFs with
more information sometimes exist; these can actually be very helpful
if you are looking for specific features.

So, actually, the day of the Manual, as such, appears to have passed.

The compiler I use is typical: early versions came with several
printed manuals; now it comes with help files and PDFs. Since these
are based on the original manuals (the PDFs, if printed, would
reproduce the manuals, in updated form), they still have a lot of
information hidden away.

So the result is that, at least for GUI programs, the easiest way to
learn it is to start it up and see what the various menu choices do. I
use a "visual source debugger", which means it runs the debugger
inside a window (with several sub-windows) and shows the source code
-- provided it was compiled in a special way. It is not, of course, an
actual /source debugger/, a possibly entirely hypothetical program for
a compiled language which would work with the source instead of just
using the source as eye candy. Very useful eye candy, to be sure, but
eye candy nonetheless.
--
"I begin to envy Petronius."
"I have envied him long since."
Robert Carnegie
2019-12-04 01:20:55 UTC
Reply
Permalink
Today I wrote some examples of how to use a particular
program that doesn't exist yet. If a colleague likes
the examples, I'll write the program. If not...
then it doesn't matter.
Ted Nolan <tednolan>
2019-12-04 01:22:57 UTC
Reply
Permalink
Post by Robert Carnegie
Today I wrote some examples of how to use a particular
program that doesn't exist yet. If a colleague likes
the examples, I'll write the program. If not...
then it doesn't matter.
There's a sort of Schrodeger's Cat nature here..
--
columbiaclosings.com
What's not in Columbia anymore..
Loading...