home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 8 Other
/
08-Other.zip
/
week_1.zip
/
Document.txt
< prev
next >
Wrap
Text File
|
1996-01-01
|
88KB
|
2,089 lines
#: 69344 S20/Marketing OS/2 Apps
25-Dec-95 13:48:33
Sb: #Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Herbert Ice 72370,2501 (X)
<<< Start new thread from # 69335-Pound Pound Pound in S20 >>>
> How importent is printed documentation to the customer?
>
> Expansion:
>
> I see it as being quite importent, but not for sure that for
> certain customers, it would not be better to have the
> documentation incorporated into the diskettes in 2 or 3 formats
> (Ascii, Describe, AmiPro) such that they could print documentation
> themselves at thier leisure. Really thinking about oversees
> customers where the difference in poundage can be substantial in
> the cost of shipping the product. Also along the lines of course,
> that this could reduce the price, percentage wise quite a bit.
Online documentation works very well for some kinds of products. I think it's
entirely appropriate when the nature of the product requires that there be a
LOT of information to wade through, and no matter how good the indexing is,
it'll never be perfect. I love having the IBM Red Books in one fat CD ROM, for
instance, because when I want to look up information about CONFIG.SYS and REXX
I don't want to have to wonder where I'm most likely to find it. Compiler
documentation is another good example of where online documentation is
valuable.
That isn't so for most general applications, though, and it's CERTAINLY not
true of the mainstream market. Don't underestimate the value of reading the
manual into the john. Don't discount the value of screen shots and pictures
and lots of handholding.
I can tell you that the documentation quality for most OS/2 software stinks.
There are some notable exceptions, but they are few and far between. (And in
the good cases you *do* know who you are because I've told you so explicitly.)
Too many OS/2 ISVs have the same person write the program that wrote the
documentation, and that's a *terrible* thing to do; even if the programmer is
a good writer (which he usually isn't) he knows too much about the product and
writes with those assumptions. The reader does *not* have the same assumptions
or knowledge and is often lost.
As an example, I'll pick on one ISV (who knows what I think of the current
documentation because we've talked about it): Colorworks. If you already know
how to use Colorworks, or if you've seen Joel demo it, the documentation makes
perfect sense. However, if you have never used an image editing program before
(much less one that changes the paradigms), the documentation is worthless.
There's no "here's the basics" chapter, there's no tutorial. There's no video
showing how to use it. When documentation is done correctly it can save the
company gobs of money, because it's clear enough that the user learns how to
use the program and doesn't call for tech support.
Look carefully at the documentation produced by the top-selling applications
in your product area. What assumptions do they make about the user's
knowledge? What tone do they write with? (Most OS/2 product manuals are dry
and lifeless; good documentation is bright and cheery and friendly, like a
good cookbook.) How often do they show the screen? I've seen entirely too many
OS/2 product manuals that completely lacked a screen shot; there's no excuse
for that. (And there's even fewer screen shots in online documentation.)
*Never* let the person who wrote the program write the documentation. And no,
that doesn't mean "convince my wife to write it" either; your spouse has been
too close to the project too. Get a real technical writer and don't blanch
when you hear their rates.
Yes, in some cases having online documentation is the right way to go. But
I've seen that used entirely too often as an excuse for doing a poor job at
writing a manual.
--Esther
There are 2 Replies.
#: 69357 S20/Marketing OS/2 Apps
25-Dec-95 23:28:29
Sb: #69344-Documentation quality
Fm: Herbert Ice 72370,2501
To: Esther Schindler [EXEC] 72241,1417
Esther,
Let me say first off, that I do believe in documentation, having waded
through IBM 370, 4341, 390 PoPs I know good doc when I see it<g>, of course
that does not mean that I can write it(unforunatly).
Personally I would not consider a software product unless it had both online,
and hardcopy doc, as I do believe in the power of the john<g>. Most of my
question really centers around, "does the documentation have to arrive in a
hardcopy with the package, or can it arrive in a fashion that the consumer can
print it out as they see fit?
Actually I think the documentation stinks for most products, whether OS/2 or
not. I will have to defend IBM documentation (mainframe), in that the PoPs I
always found to be very good, although I would imagine that came from years of
experience. I also think that the documentation that comes with Rexx for the
VM enviroment is the best I have ever seen, in that it proceeds in 3 phases,
where you go through the users manual 3 different times, building upon what
was done the prior pass for that particular chapter. This does not restrict
you from reading cover to cover, but following the manual helps unfold Rexx
like peeling an onion. Or if you will the way most of us learn, I think.
Unfortunatly, our product does not have this capability ( in some areas it
does) of progressive learning, one must comprehend it all, or nothing.
Fortunatly this is limited to the IDE, SCSI, and PCI sections. For those
sections I do not want to just retype the relevant tech. spec. (besides
copyright problems). This is an area that I have wrestled with quite a bit. I
seam to be able to explain to customers over the phone what certain portions
of the SCSI spec mean to them, and thier business, so I have defaulted to
typing in the first person in that section of the online doc. Do you feel that
is appropriate?
I would agree that the person writing the code is too close to the product,
to write decent documentation, alas in my case this will have to be done for
the first go around. Then pass the doc through a technical writer ( I know a
fine tech writer back in VA) for the second pass. As in my experience, I can
get the technical parts down, but the tech writer, raises questions that I
would never think of.
When you refer to "here's the basics", the first question I have coming back
to you is, "How basic is basic?". Let's take the area of hard drive
performance (in certain area's I am about to give up on basics, such as the
Process Information), does one have to start at the "This is a track, This is
a head, they comprise a cylynder ..." level. Or is this more a question of the
target audience?
As to screen shots, when I upload the IWSS.INF book here to Compuserve, every
screen that the product produces is included, this has had the effect of
adding hundreds of megabytes to the size of the INF, hence there will be two,
one with, and one without, such that folks can download the little one, and
get a flavor of what the product does at little cost, if there is further
interest, they can then download the monster. I see this as helping in a
couple of ways.
1. informed purchase by the consumer. Such that I am attempting to alleviate
posts on the online services of "I didn't know that this product acted in this
ridiculous fashion".
2. informed purchase by the customer. If they see the ENTIRE product prior to
purchase, I hope they will know whether it fits thier needs or not. This
should reduce thier expense and mine.
So my thesis is, show the online information to any and all that desire to
see the product. Talk about what it does, and DOES NOT do, and proceed from
that point.
My greatest fear at this point is that the product is too technical, only
time will tell.
Jay Ice
Iceware Inc.
#: 69386 S20/Marketing OS/2 Apps
26-Dec-95 11:28:43
Sb: #69357-#Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Herbert Ice 72370,2501 (X)
> Most of my question really centers around, "does the documentation
> have to arrive in a hardcopy with the package, or can it arrive in
> a fashion that the consumer can print it out as they see fit?
I'd avoid a product that required me to print it out myself. In my eyes, it
cheapens the product quality. I think of the "print it yourself" manuals as
belonging to unregistered shareware; even good shareware packages will send
you a printed manual when you register. (You don't have to create an enormous
manual; let it be the size it needs to be, and no more than that.)
In regard to "how basic?" I recommend you dig up a copy of the manual that
shipped with the original Spinrite. The first chapter gave a very basic, very
broad overview about how hard disks work; an expert could easily skip it but I
suspect that most people learned something from it. (It had a great expanation
of hard disk sectors, as I recall... and geez, I'm recalling something from a
manual I read 6+ years ago!)
Hmm, I should throw in a few other examples of what I think of as "good
documentation" that you (and lurkers) should pay attention to.
-- The manual for WordPerfect 4.0 and 4.1 (They changed its nature thereafter)
which was so in tune with its users that it had *pictures* of the function
keys that should be pressed.
-- The tutorial for Arts & Letters 1.0, which (unlike many tutorials in which
I felt that I was in a competition with myself for "how soon can I click on
all these keys?") made me feel at the end that I actually _knew_ the basics of
how to use the product.
-- CA Simply Accounting had a good manual. The product stank, but the manual
did a very good job of describing how the product worked.
> I have defaulted to typing in the first person in that section of
> the online doc. Do you feel that is appropriate?
Absolutely. Some publications really avoid writing in the first person (notice
that Computer Shopper always said, "We looked at the motherboard..." as if a
bunch of people were peering at the thing rather than one guy tearing apart
the machine in his spare room) but I find it personal. I much prefer the
first-person approach (you and I) to the impersonal "The user should type..."
Actually, I try hard to keep person-ness out of the discussion; I'll say,
"Press the space bar" rather than "You should press the space bar" or the
yucky "the user should press the space bar."
Rather than upload the file with the entire documentation, I'd pick three
screen shots and upload them in a ZIP file. You should be able to pick three
representative shots that show what your product can do; few people want to
know *everything* ahead of time... they just want to know why they should buy
it.
--Esther
--Esther
There are 3 Replies.
#: 69389 S20/Marketing OS/2 Apps
26-Dec-95 12:37:03
Sb: #69386-#Documentation quality
Fm: Michel Slivitzky 75726,243
To: Esther Schindler [EXEC] 72241,1417 (X)
First an introduction. I am not a developer, just a plain user (and lurker)
who switched to OS/2, from plain old DOS, exactly two years ago. Now running
mostly OS/2 applicaations, 3-4 DOS programs and 1-2 windows programs.
> I'd avoid a product that required me to print it out myself. In my
> eyes, it cheapens the product quality. I think of the "print it
> yourself" manuals as belonging to unregistered shareware; even
> good shareware packages will send you a printed manual when you
> register. (You don't have to create an enormous manual; let it be
> the size it needs to be, and no more than that.)
I could not agree more; I hate having to print the manuals. The manual for
Mesa2 in PS format comes to something like 400 pages !!!
Speaking about manuals, besides the "how to do it" aspect, authors (or
writers) should not forget to cover the "what can be done" aspect. Maybe most
standard products (spreadsheet, word processors) do not need it. However some
of the new aspects should be underestimated; when I moved for instance to
Describe the first manual was a pain (mainly telling how to click); the one
that came with version 5.0 was a "godsend" for really learning about the
product.
However number of special programs I have on my system (like DevTech, Unimaint
etc) would certainly benefit from good "what can be done" sections. I feel
that I am lost and probably using less than 5% of the possibilities. Once you
know (or at least have an idea) of what can be done you can search the online
help (if properly done) for the "how to do it" aspect.
IMHO the manuals ar one of the weakest points of OS/2 packages. Even something
like Lotus 1-2-3 (release 2 - for OS/2) manual is practically useless. I can
count the "good" ones on the fingers of a single hand.
Michel from Quebec City, Canada <michels@uquebec.ca>
using Warp and GCP 2.22
There is 1 Reply.
#: 69435 S20/Marketing OS/2 Apps
26-Dec-95 19:40:18
Sb: #69389-Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Michel Slivitzky 75726,243 (X)
Good point! When I talk to developers on the phone, they always tell me about
the neat feature that I can access with double alt-click metaboogie. But it's
too easy for the developer (that is, you folks) to get involved with
*features* and not solutions. Users buy solutions to their problems, _not_
software.
When you write documentation, give people a sense of what can be done with the
product. Give the basics, first -- ideally, three examples of each important
feature. But also make sure people know what's possible to accomplish. Much as
I hate to give credit to Corel, every year they put out a stunning book of
artwork done with Corel, and they run a contest for Corel artists. You can
look through the book and say, "Wow, I could do that...?!"
--Esther
#: 69344 S20/Marketing OS/2 Apps
25-Dec-95 13:48:33
Sb: #Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Herbert Ice 72370,2501 (X)
<<< Start new thread from # 69335-Pound Pound Pound in S20 >>>
> How importent is printed documentation to the customer?
>
> Expansion:
>
> I see it as being quite importent, but not for sure that for
> certain customers, it would not be better to have the
> documentation incorporated into the diskettes in 2 or 3 formats
> (Ascii, Describe, AmiPro) such that they could print documentation
> themselves at thier leisure. Really thinking about oversees
> customers where the difference in poundage can be substantial in
> the cost of shipping the product. Also along the lines of course,
> that this could reduce the price, percentage wise quite a bit.
Online documentation works very well for some kinds of products. I think it's
entirely appropriate when the nature of the product requires that there be a
LOT of information to wade through, and no matter how good the indexing is,
it'll never be perfect. I love having the IBM Red Books in one fat CD ROM, for
instance, because when I want to look up information about CONFIG.SYS and REXX
I don't want to have to wonder where I'm most likely to find it. Compiler
documentation is another good example of where online documentation is
valuable.
That isn't so for most general applications, though, and it's CERTAINLY not
true of the mainstream market. Don't underestimate the value of reading the
manual into the john. Don't discount the value of screen shots and pictures
and lots of handholding.
I can tell you that the documentation quality for most OS/2 software stinks.
There are some notable exceptions, but they are few and far between. (And in
the good cases you *do* know who you are because I've told you so explicitly.)
Too many OS/2 ISVs have the same person write the program that wrote the
documentation, and that's a *terrible* thing to do; even if the programmer is
a good writer (which he usually isn't) he knows too much about the product and
writes with those assumptions. The reader does *not* have the same assumptions
or knowledge and is often lost.
As an example, I'll pick on one ISV (who knows what I think of the current
documentation because we've talked about it): Colorworks. If you already know
how to use Colorworks, or if you've seen Joel demo it, the documentation makes
perfect sense. However, if you have never used an image editing program before
(much less one that changes the paradigms), the documentation is worthless.
There's no "here's the basics" chapter, there's no tutorial. There's no video
showing how to use it. When documentation is done correctly it can save the
company gobs of money, because it's clear enough that the user learns how to
use the program and doesn't call for tech support.
Look carefully at the documentation produced by the top-selling applications
in your product area. What assumptions do they make about the user's
knowledge? What tone do they write with? (Most OS/2 product manuals are dry
and lifeless; good documentation is bright and cheery and friendly, like a
good cookbook.) How often do they show the screen? I've seen entirely too many
OS/2 product manuals that completely lacked a screen shot; there's no excuse
for that. (And there's even fewer screen shots in online documentation.)
*Never* let the person who wrote the program write the documentation. And no,
that doesn't mean "convince my wife to write it" either; your spouse has been
too close to the project too. Get a real technical writer and don't blanch
when you hear their rates.
Yes, in some cases having online documentation is the right way to go. But
I've seen that used entirely too often as an excuse for doing a poor job at
writing a manual.
--Esther
There are 2 Replies.
#: 69363 S20/Marketing OS/2 Apps
26-Dec-95 04:11:45
Sb: #69344-Documentation quality
Fm: Samuel G. Little 70544,10
To: Esther Schindler [EXEC] 72241,1417
PMJI, Esther, but I think there are a few other things to consider: the
capabilities / needs of the target audience, and the type of application.
Programming languages are as good an example of the latter point as any. Being
of the "old school" of programmers, I will typically use paper and pencil to
work out the general structure of my programs (e.g., I start with pseudocode),
then try to iron out what functions or macros I need to use. For most of this
process, I don't find the computer as convenient a medium as a printed book or
manual. This is one of the reasons I printed the Rexx documentation.
Most of my programs have a target audience of 15: ten computer operations
staff and the other five programmers in my group. Now, none of the CompOps
staff are terribly familiar with OS/2 (let alone the programmers!), and a few
have basic conceptual difficulties with the WPS interface, despite my best
efforts to explain (context menus are the hardest to deal with).
About half of them can *only* deal with step-by-step instructions. Any sort of
error which isn't documented, with instructions on what to do next, and I get
phone calls in the wee hours. I walk them through the solution, ask them to
write down the error message(s) and put it in my mailbox, and I spend my first
two hours when I come in in the morning updating and reprinting the
documentation. (BTW, for the OS/2 stuff, I do use screen and window shots).
It's been found that on-line documentation doesn't work very well for this
"audience" through other systems that they have to support.
Some people -- and situations -- just aren't suited for on-line or print-only
documentation.
--Sam. (Warped & using GCP 2.20c)
sam_little@iacnet.com
#: 69387 S20/Marketing OS/2 Apps
26-Dec-95 11:28:44
Sb: #69363-Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Samuel G. Little 70544,10 (X)
Good point, Sam!
(And *never* apologize for jumping in. The purpose of this conversation is to
involve several people; if we wanted it to be private, we'd be in email.
<smile>)
--Esther
#: 69344 S20/Marketing OS/2 Apps
25-Dec-95 13:48:33
Sb: #Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Herbert Ice 72370,2501 (X)
<<< Start new thread from # 69335-Pound Pound Pound in S20 >>>
> How importent is printed documentation to the customer?
>
> Expansion:
>
> I see it as being quite importent, but not for sure that for
> certain customers, it would not be better to have the
> documentation incorporated into the diskettes in 2 or 3 formats
> (Ascii, Describe, AmiPro) such that they could print documentation
> themselves at thier leisure. Really thinking about oversees
> customers where the difference in poundage can be substantial in
> the cost of shipping the product. Also along the lines of course,
> that this could reduce the price, percentage wise quite a bit.
Online documentation works very well for some kinds of products. I think it's
entirely appropriate when the nature of the product requires that there be a
LOT of information to wade through, and no matter how good the indexing is,
it'll never be perfect. I love having the IBM Red Books in one fat CD ROM, for
instance, because when I want to look up information about CONFIG.SYS and REXX
I don't want to have to wonder where I'm most likely to find it. Compiler
documentation is another good example of where online documentation is
valuable.
That isn't so for most general applications, though, and it's CERTAINLY not
true of the mainstream market. Don't underestimate the value of reading the
manual into the john. Don't discount the value of screen shots and pictures
and lots of handholding.
I can tell you that the documentation quality for most OS/2 software stinks.
There are some notable exceptions, but they are few and far between. (And in
the good cases you *do* know who you are because I've told you so explicitly.)
Too many OS/2 ISVs have the same person write the program that wrote the
documentation, and that's a *terrible* thing to do; even if the programmer is
a good writer (which he usually isn't) he knows too much about the product and
writes with those assumptions. The reader does *not* have the same assumptions
or knowledge and is often lost.
As an example, I'll pick on one ISV (who knows what I think of the current
documentation because we've talked about it): Colorworks. If you already know
how to use Colorworks, or if you've seen Joel demo it, the documentation makes
perfect sense. However, if you have never used an image editing program before
(much less one that changes the paradigms), the documentation is worthless.
There's no "here's the basics" chapter, there's no tutorial. There's no video
showing how to use it. When documentation is done correctly it can save the
company gobs of money, because it's clear enough that the user learns how to
use the program and doesn't call for tech support.
Look carefully at the documentation produced by the top-selling applications
in your product area. What assumptions do they make about the user's
knowledge? What tone do they write with? (Most OS/2 product manuals are dry
and lifeless; good documentation is bright and cheery and friendly, like a
good cookbook.) How often do they show the screen? I've seen entirely too many
OS/2 product manuals that completely lacked a screen shot; there's no excuse
for that. (And there's even fewer screen shots in online documentation.)
*Never* let the person who wrote the program write the documentation. And no,
that doesn't mean "convince my wife to write it" either; your spouse has been
too close to the project too. Get a real technical writer and don't blanch
when you hear their rates.
Yes, in some cases having online documentation is the right way to go. But
I've seen that used entirely too often as an excuse for doing a poor job at
writing a manual.
--Esther
There are 2 Replies.
#: 69426 S20/Marketing OS/2 Apps
26-Dec-95 17:40:10
Sb: #69344-#Documentation quality
Fm: Felix Cruz 72274,3102
To: Esther Schindler [EXEC] 72241,1417 (X)
Esther,
Your points about documentation are noted.
I usually load a program and then try to use it without reading the docs
(don't most end users do this? ;-) )
I agree the supporting manual should be clearly written, with a "how-to"
section, supporting screen shots, as well as an introduction into the
product's capabilities. We plan to revise the product manuals as each goes
through its product cycles to orient them from the perspective of a casual,
unsophisticated user.
Although most people won't read them, a product's manual *does* add value to
the product, so we will continue to include them.
Felix Cruz
SofTouch Systems, Inc
There are 2 Replies.
#: 69433 S20/Marketing OS/2 Apps
26-Dec-95 19:26:43
Sb: #69426-#Documentation quality
Fm: Michel Slivitzky 75726,243
To: Felix Cruz 72274,3102 (X)
> Although most people won't read them, a product's manual *does*
> add value to the product, so we will continue to include them.
I read all manuals that I have for SofTouch products (three of them); they
are good even if the one for Unimaint is somewhat "light" IMHO on the "What
can be done" aspect. There are so many things that can be done with it; I
probably missed about 70% of them.
Michel from Quebec City, Canada <michels@uquebec.ca>
using Warp and GCP 2.22
There is 1 Reply.
#: 69452 S20/Marketing OS/2 Apps
27-Dec-95 00:11:52
Sb: #69433-Documentation quality
Fm: Felix Cruz 72274,3102
To: Michel Slivitzky 75726,243 (X)
Michel,
Thanks for letting us know how useful the product manuals are to you. We will
continue to enhance them by adding more in the "how-to" area.
The relevant point to the discussion here is that manuals can always be
improved upon, and they are an essential component of a successful product.
Felix Cruz
SofTouch Systems, Inc
#: 69386 S20/Marketing OS/2 Apps
26-Dec-95 11:28:43
Sb: #69357-#Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Herbert Ice 72370,2501 (X)
> Most of my question really centers around, "does the documentation
> have to arrive in a hardcopy with the package, or can it arrive in
> a fashion that the consumer can print it out as they see fit?
I'd avoid a product that required me to print it out myself. In my eyes, it
cheapens the product quality. I think of the "print it yourself" manuals as
belonging to unregistered shareware; even good shareware packages will send
you a printed manual when you register. (You don't have to create an enormous
manual; let it be the size it needs to be, and no more than that.)
In regard to "how basic?" I recommend you dig up a copy of the manual that
shipped with the original Spinrite. The first chapter gave a very basic, very
broad overview about how hard disks work; an expert could easily skip it but I
suspect that most people learned something from it. (It had a great expanation
of hard disk sectors, as I recall... and geez, I'm recalling something from a
manual I read 6+ years ago!)
Hmm, I should throw in a few other examples of what I think of as "good
documentation" that you (and lurkers) should pay attention to.
-- The manual for WordPerfect 4.0 and 4.1 (They changed its nature thereafter)
which was so in tune with its users that it had *pictures* of the function
keys that should be pressed.
-- The tutorial for Arts & Letters 1.0, which (unlike many tutorials in which
I felt that I was in a competition with myself for "how soon can I click on
all these keys?") made me feel at the end that I actually _knew_ the basics of
how to use the product.
-- CA Simply Accounting had a good manual. The product stank, but the manual
did a very good job of describing how the product worked.
> I have defaulted to typing in the first person in that section of
> the online doc. Do you feel that is appropriate?
Absolutely. Some publications really avoid writing in the first person (notice
that Computer Shopper always said, "We looked at the motherboard..." as if a
bunch of people were peering at the thing rather than one guy tearing apart
the machine in his spare room) but I find it personal. I much prefer the
first-person approach (you and I) to the impersonal "The user should type..."
Actually, I try hard to keep person-ness out of the discussion; I'll say,
"Press the space bar" rather than "You should press the space bar" or the
yucky "the user should press the space bar."
Rather than upload the file with the entire documentation, I'd pick three
screen shots and upload them in a ZIP file. You should be able to pick three
representative shots that show what your product can do; few people want to
know *everything* ahead of time... they just want to know why they should buy
it.
--Esther
--Esther
There are 3 Replies.
#: 69403 S20/Marketing OS/2 Apps
26-Dec-95 13:46:04
Sb: #69386-#Documentation quality
Fm: Herbert Ice 72370,2501
To: Esther Schindler [EXEC] 72241,1417 (X)
Esther,
> (You don't have to create an enormous manual; let it be the size
> it needs to be, and no more than that.)
The above is the nut of the problem, to be done right, it could easily hit
200+ pages. I mean how big is the relevant portions of the Scsi-II spec, IDE
spec, Internals of OS/2, how can settings of the config.sys impact one of the
performance benchmarks?
I don't feel that I can upload just 3 screen shots, that is too low of a
percentage of the windows, and not representative of the functionality of the
product.
Jay Ice
Iceware Inc.
There is 1 Reply.
#: 69436 S20/Marketing OS/2 Apps
26-Dec-95 19:40:21
Sb: #69403-Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Herbert Ice 72370,2501 (X)
I think the confusion on "how much documentation" here stems from the
definition you have for "who is your user?"
You have permission to read ahead in the book, Jay -- skip ahead to chapter 4
and read through the section entitled "Sample Scenario."
I don't think you're writing your application for my next door neighbor, the
nice sweet lady who called me yesterday afternoon to ask me to help her
install Myst. (She didn't know that her CD ROM drive had a letter associated
with it. "Type E colon backslash... no the OTHER slash...") Just as Spinrite
was aimed at and successful with techies, so will your audience be -- at least
in the first version. Give THOSE people the basics of what they need to know
to intelligently use your product. How much do I need to know about the SCSI
spec in order to get the most out of the product? Tell me that much, and not
much more.
> I don't feel that I can upload just 3 screen shots, that is too
> low of a percentage of the windows, and not representative of the
> functionality of the product.
If that's so, then you have a serious problem in the design of the product. I
can tell you already that as a reviewer you'd get a *maximum* of three screen
shots in an in-depth review, and probably only one. If it helps you any...
which three screens would you wish I'd choose to include? Use those. (You may
"cheat" and look at reviews of products you know well... and try to figure out
why the reviewer included the screen shots she did.)
--Esther
#: 69477 S20/Marketing OS/2 Apps
27-Dec-95 12:28:08
Sb: #69436-#Documentation quality
Fm: Herbert Ice 72370,2501
To: Esther Schindler [EXEC] 72241,1417 (X)
Esther,
No, it's not for your neighbor, to use on a daily basis, why the product is
for your nieghbor, is that while very few people are truly professional
carpenters/mechanics I'll bet dollars to donuts (or even chocolate for that
matter<g>). That most folks do have a hammer or screwdriver in thier
possesion. This is the analogy that I draw when folks question why they would
need it. No you may not understand everything (although if the doc is written
correctly that can be PARTIALLY aleviated), but when you don't I'll bet that
you call someone who you feel does, now you can give them the information
easily, even down to the point of inspecting I/O ports without writing one
line of code (don't snicker it can be helpfull when looking at IDE hard
drives<G>). I may have missed the boat totally, only time can tell. In general
it will be the power user and above that gravitates to the product though.
A reviewer could quite easily pick out 3 different screen shots, what I was
thinking when I wrote that, was along the lines of there is a lot in this, and
to distill it down to 3 shots, somehow feels like cutting the products throat,
a reviewer would not have that egotistical problem, which I do. As to the 3
screens a reviewer would choose it would depend on the periodical. For OS/2
magazine, the opening screen (as it shows all the chiseled buttons for
invoking every function), the multitasking command line, then probably the
performance stuff (of course that is 3 main windows in and of itself). For
IBM's journal, the main, scsi, IRQ usage, would be the flavor that I would
want to represent.
Jay Ice
Iceware Inc.
There is 1 Reply.
#: 69509 S20/Marketing OS/2 Apps
27-Dec-95 20:29:26
Sb: #69477-Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Herbert Ice 72370,2501
I think you're still being unclear about who will buy your product. The answer
could be as simple as, "The same people who purchase Gammatech Utilities or
Partition Magic" (in which case you find yourself with a _really_ good clue
about partnering for effective cooperative marketing), or as complex as
"Anyone who needs to manage or maintain OS/2 systems to the peak of their
performance."
In other words, I'm trying to get you to define, explicitly, who will USE your
program.
The second step is to define who will _buy_ the product which (as can be
easily demonstrated in a corporate environment) might be a very different
answer.
You're going to start out with power users. EVERYONE starts out with the early
adopters... or they wouldn't be called early adopters, now would they? <grin>
So design your message to appeal to them (the people who own _lots_ of
screwdrivers, not to mention a model train set, a complex kitchen gadget, and
a ham radio setup), but keep in mind that the eventual audience is much
bigger.
Norton Utilities' marketing really is a good model for you; originally it was
for the techies, but eventually it was marketed as the *lifesaver,* the tool
to have around if you're afraid of what could happen. I'm sure that plenty of
packages were purchased and never used, like kitchen fire extinguishers. But
notice the distinction between the early market (people who liked to muck
about with their boot records), the mainstream market (people who want the
security of a spare tire in the trunk) to the eventual use with the laggards
(subset of utilities bundled with the OS and thus invisible to the user).
> to distill it down to 3 shots, somehow feels like cutting the
> products throat
Jay, you _must_ find a way to do this. If for no other reason, if *you* don't
find a way to express the product's purpose in two sentences or less (and 3
screen shots or less) than other people will. A good part of what PR is really
about is defining the message you want people to get in their heads about your
company and your product. If you don't create an image, others will create it
for you... and that image might or might not be one that you'd choose.
Your first effort was good (though I rarely show the opening screen for
anything <grin>). Now improve it. <smile>
--Esther
#: 69630 S20/Marketing OS/2 Apps
28-Dec-95 23:54:46
Sb: #69509-Documentation quality
Fm: Herbert Ice 72370,2501
To: Esther Schindler [EXEC] 72241,1417
Esther,
> I think you're still being unclear about who will buy your product.
You are most correct, as I am quite unsure who will actually USE the product
to it's full potential. Some days I feel that only OEMs could, but somehow it
feels that I have distilled enough of the technical stuff down to a somewhat
usable interface, that anyone who cares about the main features will.
As to who will BUY the product, that for me is quite simple, technical
people, pure and simple. It was never designed to be a pretty or cutesy, it
was designed to give me answers to questions that I have had about computers
since becoming a VM systems programmer. Running scenerios to see how things
change etc. So to sum it up, it will be technical folks in the beggining who
desire answers or at least closer approximations to answers than what they can
get today.
I agree on the Norton utilites, and with the evolution of same.
To sum the product up in two sentences or less, just being a hick from the
sticks, I would say,
To learn, to improve, to save your ass!!!<g>.
Well I am being a donkey with the last noun, but the above three phrases do
sum it up for me.
Esther thank you ever so much for making me think about these things.
Jay Ice
Iceware Inc.
#: 69704 S20/Marketing OS/2 Apps
29-Dec-95 22:28:20
Sb: #69630-#Documentation quality
Fm: Buck Bohac 70670,2352
To: Herbert Ice 72370,2501 (X)
Hi Jay,
> As to who will BUY the product, that for me is quite simple,
> technical people, pure and simple. It was never designed to be a
> pretty or cutesy, it was designed to give me answers to questions
> that I have had about computers since becoming a VM systems
> programmer.
One quick thought. I have NEVER seen or heard a technical person complain
that an application or procedure was too easy to implement or use. On the
other hand ...!
Buck
There is 1 Reply.
#: 69725 S20/Marketing OS/2 Apps
30-Dec-95 00:55:35
Sb: #69704-Documentation quality
Fm: Herbert Ice 72370,2501
To: Buck Bohac 70670,2352
Buck,
Agreed, but I have heard plenty of technical people complain about tools that
lacked depth, that while they were purported/hyped to be the last thing they
ever needed, it never even got close. By pretty and cutesy, I am referring to
a lot of fancy graphics, I have only used standard PM controls, trying to get
the information out first, the michelangelos can follow.
Jay Ice
Iceware Inc.
#: 69386 S20/Marketing OS/2 Apps
26-Dec-95 11:28:43
Sb: #69357-#Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Herbert Ice 72370,2501 (X)
> Most of my question really centers around, "does the documentation
> have to arrive in a hardcopy with the package, or can it arrive in
> a fashion that the consumer can print it out as they see fit?
I'd avoid a product that required me to print it out myself. In my eyes, it
cheapens the product quality. I think of the "print it yourself" manuals as
belonging to unregistered shareware; even good shareware packages will send
you a printed manual when you register. (You don't have to create an enormous
manual; let it be the size it needs to be, and no more than that.)
In regard to "how basic?" I recommend you dig up a copy of the manual that
shipped with the original Spinrite. The first chapter gave a very basic, very
broad overview about how hard disks work; an expert could easily skip it but I
suspect that most people learned something from it. (It had a great expanation
of hard disk sectors, as I recall... and geez, I'm recalling something from a
manual I read 6+ years ago!)
Hmm, I should throw in a few other examples of what I think of as "good
documentation" that you (and lurkers) should pay attention to.
-- The manual for WordPerfect 4.0 and 4.1 (They changed its nature thereafter)
which was so in tune with its users that it had *pictures* of the function
keys that should be pressed.
-- The tutorial for Arts & Letters 1.0, which (unlike many tutorials in which
I felt that I was in a competition with myself for "how soon can I click on
all these keys?") made me feel at the end that I actually _knew_ the basics of
how to use the product.
-- CA Simply Accounting had a good manual. The product stank, but the manual
did a very good job of describing how the product worked.
> I have defaulted to typing in the first person in that section of
> the online doc. Do you feel that is appropriate?
Absolutely. Some publications really avoid writing in the first person (notice
that Computer Shopper always said, "We looked at the motherboard..." as if a
bunch of people were peering at the thing rather than one guy tearing apart
the machine in his spare room) but I find it personal. I much prefer the
first-person approach (you and I) to the impersonal "The user should type..."
Actually, I try hard to keep person-ness out of the discussion; I'll say,
"Press the space bar" rather than "You should press the space bar" or the
yucky "the user should press the space bar."
Rather than upload the file with the entire documentation, I'd pick three
screen shots and upload them in a ZIP file. You should be able to pick three
representative shots that show what your product can do; few people want to
know *everything* ahead of time... they just want to know why they should buy
it.
--Esther
--Esther
There are 3 Replies.
#: 69407 S20/Marketing OS/2 Apps
26-Dec-95 14:19:38
Sb: #69386-#Documentation quality
Fm: Guy Scharf [Sysop] 76702,557
To: Esther Schindler [EXEC] 72241,1417 (X)
Esther,
Speaking entirely as a user, I have a pet peeve about printing user manuals.
First, I don't like to do it. A manual printed on 8.5x11 paper looseleaf is
more unwieldy than a perfect-bound, smaller-sized manual.
But, more importantly, I have generally not be able to get the manuals to
print double sided, which uses 2x as much paper as it needs to. I *do* have a
duplex printer, and one of my purposes is to save paper. Yes, I suppose if I
knew PostScript I might be able to figure out how to edit it to use the duplex
feature, but that really shouldn't be required of the user.
As a user, I want the manual both in printed form *and* online! And I want
both of them to be complete. Online is very useful for reference material and
looking things up while I am working on the computer; printed is essential for
study and for learning a product. All of the vendors I have seen who have
opted for electronic manuals only seem to speak to the needs of the
established customer and are raising the barrier for the new customer by
making their product more difficult to use than it need be.
Case in point: Quicken for Windows Deluxe version. The diskette version has
printed manuals. The CD-ROM version has more information on the CD-ROM but
lacks printed manuals. I want the additional features, and I also want the
printed manuals. The fact that I can't get both in one box has delayed my
purchase by months, and may delay it indefinitely as I decide the previous
version continues to meet my needs well.
Guy
There is 1 Reply.
#: 69437 S20/Marketing OS/2 Apps
26-Dec-95 19:40:22
Sb: #69407-Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Guy Scharf [Sysop] 76702,557 (X)
<<Esther nods enthusiastically, in agreement>>
#: 69426 S20/Marketing OS/2 Apps
26-Dec-95 17:40:10
Sb: #69344-#Documentation quality
Fm: Felix Cruz 72274,3102
To: Esther Schindler [EXEC] 72241,1417 (X)
Esther,
Your points about documentation are noted.
I usually load a program and then try to use it without reading the docs
(don't most end users do this? ;-) )
I agree the supporting manual should be clearly written, with a "how-to"
section, supporting screen shots, as well as an introduction into the
product's capabilities. We plan to revise the product manuals as each goes
through its product cycles to orient them from the perspective of a casual,
unsophisticated user.
Although most people won't read them, a product's manual *does* add value to
the product, so we will continue to include them.
Felix Cruz
SofTouch Systems, Inc
There are 2 Replies.
#: 69443 S20/Marketing OS/2 Apps
26-Dec-95 22:49:45
Sb: #69426-#Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Felix Cruz 72274,3102 (X)
Early adopters like us pride ourselves on the fact that we've never read the
manual. Ordinary users *do* read them... and are usually confused.
Apropos of this whole discussion, my next door neighbor (the one who bought a
home computer a year ago "so I could start to do some writing") called me
yesterday afternoon to ask me to help her install Myst. The short version of
the problem was that she didn't know how to tell windows "E:\setup.exe" --
because the manual said X:SETUP.EXE, and she sure didn't have an X drive. It
did say to substitute the CD ROM driver letter for X, but she didn't know the
CD ROM drive even *had* a drive letter, or what one was.
I talk to these people because they keep me honest. I'll rent Michelle to you,
anytime you need the same experience. <grin> (She's nice, she's pretty, she's
divorced... she has 4 kids...)
--Esther
There is 1 Reply.
#: 69451 S20/Marketing OS/2 Apps
27-Dec-95 00:11:50
Sb: #69443-Documentation quality
Fm: Felix Cruz 72274,3102
To: Esther Schindler [EXEC] 72241,1417
Esther,
"Ordinary users *do* read them... and are usually confused."
Agreed. That is why the road to "perfect" documentation is always under
construction. <s>
BTW - We intend to approach the whole useability issue from a different
standpoint for some upcoming product upgrades by complementing the product
manual with another technique to see if this improves the customer's
experience with our products.
Felix Cruz
SofTouch Systems, Inc
#: 69478 S20/Marketing OS/2 Apps
27-Dec-95 12:31:51
Sb: #69451-#Documentation quality
Fm: Jim Beyer- Asst DIABETES 73060,1544
To: Felix Cruz 72274,3102 (X)
I am a big booster of technical writers. I have gone so far as to make one a
partner in my current venture. I am a developer, I know about designing
software and creating it. I am not a technical writer, so I want on on staff.
Back to lurker mode.
FWIW
JimB [Asst DIABETES]
There is 1 Reply.
#: 69511 S20/Marketing OS/2 Apps
27-Dec-95 21:40:19
Sb: #69478-Documentation quality
Fm: Felix Cruz 72274,3102
To: Jim Beyer- Asst DIABETES 73060,1544
Jim,
> I am a big booster of technical writers. <
Agreed. Now, where was this discussion going? <g>
Felix Cruz
SofTouch Systems, Inc
#: 69443 S20/Marketing OS/2 Apps
26-Dec-95 22:49:45
Sb: #69426-#Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Felix Cruz 72274,3102 (X)
Early adopters like us pride ourselves on the fact that we've never read the
manual. Ordinary users *do* read them... and are usually confused.
Apropos of this whole discussion, my next door neighbor (the one who bought a
home computer a year ago "so I could start to do some writing") called me
yesterday afternoon to ask me to help her install Myst. The short version of
the problem was that she didn't know how to tell windows "E:\setup.exe" --
because the manual said X:SETUP.EXE, and she sure didn't have an X drive. It
did say to substitute the CD ROM driver letter for X, but she didn't know the
CD ROM drive even *had* a drive letter, or what one was.
I talk to these people because they keep me honest. I'll rent Michelle to you,
anytime you need the same experience. <grin> (She's nice, she's pretty, she's
divorced... she has 4 kids...)
--Esther
There is 1 Reply.
#: 69487 S20/Marketing OS/2 Apps
27-Dec-95 14:34:20
Sb: #69443-#Documentation quality
Fm: Jon Duringer[IdeaFa 71732,3361
To: Esther Schindler [EXEC] 72241,1417 (X)
>> Ordinary users *do* read them...
OS/2 and SOM allow us to create products that are radically simpler than
conventional software products. It will take us several years to even grok
how simple desktop objects can be. When we finally do, I think that the idea
of writing a manual will come to seem as silly as writing a manual on how to
use a pad of paper would be.
There are 2 Replies.
#: 69499 S20/Marketing OS/2 Apps
27-Dec-95 18:58:48
Sb: #69487-#Documentation quality
Fm: Samuel G. Little 70544,10
To: Jon Duringer[IdeaFa 71732,3361 (X)
> When we finally do, I think that the idea of writing a manual will
> come to seem as silly as writing a manual on how to use a pad of
> paper would be.
I doubt this will ever occur, Jon.
<Deconstructionalist hat on>
No matter what, one is constricted by language, and communication through
language or symbol is always faulty. The only way to overcome it is to attempt
to be as specific as possible, often taking multiple approaches. Most good
dictionaries provide two or three similar definitions for a word for just such
a reason.
Take almost any action name used by two or three different programs, and I'll
bet none of them do quite the same thing. Same word, different language. These
differences will always exist (though they may be reduced) and will have to be
explained.
<deconstructionalist hat off>
--Sam. (Warped & using GCP 2.22)
sam_little@iacnet.com
There is 1 Reply.
#: 69501 S20/Marketing OS/2 Apps
27-Dec-95 19:27:46
Sb: #69499-Documentation quality
Fm: Jon Duringer[IdeaFa 71732,3361
To: Samuel G. Little 70544,10
>> I doubt this will ever occur, Jon.
Let me put my thought this way. Suppose documenting software products became
absolutely illegal and impossible. Would the software industry disappear?
No, we'd just be forced to fully exploit SOM and OS/2 to create simple,
visually intuitive objects which corresponded closely to physical objects that
everyone is familiar with. The objects would need to be safe, intriguing, and
indestructable, kind of like the objects that we give to 2 year old toddlers.
The objects would have to do interesting things when manipulated in simple,
general ways. The software industry wouldn't disappear, but it -would- be
radically transformed.
Samuel, this is where we need to go to eliminate Moore's Chasm. With OS/2, we
-can- do this. Let's set our sights on it, and spend the next 10 years
getting there.
In the short term, we do need to write better documentation. In the longer
term, we need to start thinking about eliminating the need for documentation
altogther, to make our products like crayons, pads of paper, and staplers.
#: 69539 S20/Marketing OS/2 Apps
28-Dec-95 00:56:17
Sb: #69501-#Documentation quality
Fm: Samuel G. Little 70544,10
To: Jon Duringer[IdeaFa 71732,3361 (X)
> Suppose documenting software products became absolutely illegal
> and impossible. Would the software industry disappear? No, we'd
> just be forced to fully exploit SOM and OS/2 to create simple,
> visually intuitive objects which corresponded closely to physical
> objects that everyone is familiar with.
As my grandmother taught blind children and my mother tutored developmentally
disabled people, this just *isn't* possible. To many people, the difference
between a dining room chair and a recliner are merely cosmetic. To others who
are only familiar with one, the other is incomprehensible.
Any visual (or audial) object is a symbol. IMO, any programmer who relies on
the intuition of his customer is going to be disappointed with the outcome.
The only way it could work is if every customer had the same experiential and
symbolic background ... or if the objects were not designed to do any work (as
in the objects one gives 2-year-olds).
--Sam. (Warped & using GCP 2.22)
sam_little@iacnet.com
There is 1 Reply.
#: 69563 S20/Marketing OS/2 Apps
28-Dec-95 09:49:50
Sb: #69539-#Documentation quality
Fm: Jon Duringer[IdeaFa 71732,3361
To: Samuel G. Little 70544,10 (X)
>>To others who are only familiar with one, the other is incomprehensible.
What if the recliner detected the presence of a blind person, invited her to
sit down, and then slowly extended itself, whispering, "This is what I do... I
am a recliner... Doesn't that feel good..." Perhaps sentience is the key.
>> if the objects were not designed to do any work (as in the objects one
gives 2-year-olds).
Perhaps what I'm suggesting isn't possible. I certainly haven't created an
object of the class that we're discussing. But I think that I'm going to try
to whip up some examples, just to explore what really can be done.
There is 1 Reply.
#: 69601 S20/Marketing OS/2 Apps
28-Dec-95 19:01:44
Sb: #69563-#Documentation quality
Fm: Samuel G. Little 70544,10
To: Jon Duringer[IdeaFa 71732,3361 (X)
> Perhaps what I'm suggesting isn't possible.
Any and every interface is exclusionary to some subset of potential user
population. I suppose such exclusions can be minimized given a large number of
interface parts and the ability of each object to tell that interface part
what it is, so that it doesn't matter whether the interface is graphic, text
or audial (in any language), or direct-to-brain interface!
I don't see this coming anytime in the near future, though....
--Sam. (Warped & using GCP 2.22)
sam_little@iacnet.com
There is 1 Reply.
#: 69608 S20/Marketing OS/2 Apps
28-Dec-95 19:34:03
Sb: #69601-Documentation quality
Fm: Jon Duringer[IdeaFa 71732,3361
To: Samuel G. Little 70544,10
>> I don't see this coming anytime in the near future, though....
I know what you mean. We have to focus on making sure there's food on the
table. Still, the tools are at hand, and it wouldn't hurt to get started....
#: 69487 S20/Marketing OS/2 Apps
27-Dec-95 14:34:20
Sb: #69443-#Documentation quality
Fm: Jon Duringer[IdeaFa 71732,3361
To: Esther Schindler [EXEC] 72241,1417 (X)
>> Ordinary users *do* read them...
OS/2 and SOM allow us to create products that are radically simpler than
conventional software products. It will take us several years to even grok
how simple desktop objects can be. When we finally do, I think that the idea
of writing a manual will come to seem as silly as writing a manual on how to
use a pad of paper would be.
There are 2 Replies.
#: 69510 S20/Marketing OS/2 Apps
27-Dec-95 20:29:27
Sb: #69487-#Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Jon Duringer[IdeaFa 71732,3361 (X)
Yeah, right.
When that day happens, let's talk about it.
In the meantime, I don't feel any danger that my skills as technical writer
will become irrelevant.
--Esther
There is 1 Reply.
#: 69529 S20/Marketing OS/2 Apps
27-Dec-95 23:52:36
Sb: #69510-Documentation quality
Fm: Jon Duringer[IdeaFa 71732,3361
To: Esther Schindler [EXEC] 72241,1417
>> Yeah, right. When that day happens, let's talk about it.
Just you wait, Ms. Esther Schindler. I'll show youuuu...... <s>
(It might take me a few years, but I have a feeling that you've just lit a
fire in my heart that isn't going to go out.)
#: 69344 S20/Marketing OS/2 Apps
25-Dec-95 13:48:33
Sb: #Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Herbert Ice 72370,2501 (X)
<<< Start new thread from # 69335-Pound Pound Pound in S20 >>>
> How importent is printed documentation to the customer?
>
> Expansion:
>
> I see it as being quite importent, but not for sure that for
> certain customers, it would not be better to have the
> documentation incorporated into the diskettes in 2 or 3 formats
> (Ascii, Describe, AmiPro) such that they could print documentation
> themselves at thier leisure. Really thinking about oversees
> customers where the difference in poundage can be substantial in
> the cost of shipping the product. Also along the lines of course,
> that this could reduce the price, percentage wise quite a bit.
Online documentation works very well for some kinds of products. I think it's
entirely appropriate when the nature of the product requires that there be a
LOT of information to wade through, and no matter how good the indexing is,
it'll never be perfect. I love having the IBM Red Books in one fat CD ROM, for
instance, because when I want to look up information about CONFIG.SYS and REXX
I don't want to have to wonder where I'm most likely to find it. Compiler
documentation is another good example of where online documentation is
valuable.
That isn't so for most general applications, though, and it's CERTAINLY not
true of the mainstream market. Don't underestimate the value of reading the
manual into the john. Don't discount the value of screen shots and pictures
and lots of handholding.
I can tell you that the documentation quality for most OS/2 software stinks.
There are some notable exceptions, but they are few and far between. (And in
the good cases you *do* know who you are because I've told you so explicitly.)
Too many OS/2 ISVs have the same person write the program that wrote the
documentation, and that's a *terrible* thing to do; even if the programmer is
a good writer (which he usually isn't) he knows too much about the product and
writes with those assumptions. The reader does *not* have the same assumptions
or knowledge and is often lost.
As an example, I'll pick on one ISV (who knows what I think of the current
documentation because we've talked about it): Colorworks. If you already know
how to use Colorworks, or if you've seen Joel demo it, the documentation makes
perfect sense. However, if you have never used an image editing program before
(much less one that changes the paradigms), the documentation is worthless.
There's no "here's the basics" chapter, there's no tutorial. There's no video
showing how to use it. When documentation is done correctly it can save the
company gobs of money, because it's clear enough that the user learns how to
use the program and doesn't call for tech support.
Look carefully at the documentation produced by the top-selling applications
in your product area. What assumptions do they make about the user's
knowledge? What tone do they write with? (Most OS/2 product manuals are dry
and lifeless; good documentation is bright and cheery and friendly, like a
good cookbook.) How often do they show the screen? I've seen entirely too many
OS/2 product manuals that completely lacked a screen shot; there's no excuse
for that. (And there's even fewer screen shots in online documentation.)
*Never* let the person who wrote the program write the documentation. And no,
that doesn't mean "convince my wife to write it" either; your spouse has been
too close to the project too. Get a real technical writer and don't blanch
when you hear their rates.
Yes, in some cases having online documentation is the right way to go. But
I've seen that used entirely too often as an excuse for doing a poor job at
writing a manual.
--Esther
There are 2 Replies.
#: 69519 S20/Marketing OS/2 Apps
27-Dec-95 22:02:49
Sb: #69344-Documentation quality
Fm: Shmuel Metz (Atid/2) 71054,3066
To: Esther Schindler [EXEC] 72241,1417 (X)
>> Get a real technical writer and don't blanch when you hear their rates. <<
But review everything that he does to ensure technical accuracy; I've seen too
many cases where the manual reads like a racy novel, but it doesn't match the
product. Plan on putting in a lot of your own time on top of what you pay the
tech writer.
Shmuel (Seymour J.) Metz, SysProg & JOAT, Atid/2, Team OS/2, Team PL/I
#: 69357 S20/Marketing OS/2 Apps
25-Dec-95 23:28:29
Sb: #69344-Documentation quality
Fm: Herbert Ice 72370,2501
To: Esther Schindler [EXEC] 72241,1417
Esther,
Let me say first off, that I do believe in documentation, having waded
through IBM 370, 4341, 390 PoPs I know good doc when I see it<g>, of course
that does not mean that I can write it(unforunatly).
Personally I would not consider a software product unless it had both online,
and hardcopy doc, as I do believe in the power of the john<g>. Most of my
question really centers around, "does the documentation have to arrive in a
hardcopy with the package, or can it arrive in a fashion that the consumer can
print it out as they see fit?
Actually I think the documentation stinks for most products, whether OS/2 or
not. I will have to defend IBM documentation (mainframe), in that the PoPs I
always found to be very good, although I would imagine that came from years of
experience. I also think that the documentation that comes with Rexx for the
VM enviroment is the best I have ever seen, in that it proceeds in 3 phases,
where you go through the users manual 3 different times, building upon what
was done the prior pass for that particular chapter. This does not restrict
you from reading cover to cover, but following the manual helps unfold Rexx
like peeling an onion. Or if you will the way most of us learn, I think.
Unfortunatly, our product does not have this capability ( in some areas it
does) of progressive learning, one must comprehend it all, or nothing.
Fortunatly this is limited to the IDE, SCSI, and PCI sections. For those
sections I do not want to just retype the relevant tech. spec. (besides
copyright problems). This is an area that I have wrestled with quite a bit. I
seam to be able to explain to customers over the phone what certain portions
of the SCSI spec mean to them, and thier business, so I have defaulted to
typing in the first person in that section of the online doc. Do you feel that
is appropriate?
I would agree that the person writing the code is too close to the product,
to write decent documentation, alas in my case this will have to be done for
the first go around. Then pass the doc through a technical writer ( I know a
fine tech writer back in VA) for the second pass. As in my experience, I can
get the technical parts down, but the tech writer, raises questions that I
would never think of.
When you refer to "here's the basics", the first question I have coming back
to you is, "How basic is basic?". Let's take the area of hard drive
performance (in certain area's I am about to give up on basics, such as the
Process Information), does one have to start at the "This is a track, This is
a head, they comprise a cylynder ..." level. Or is this more a question of the
target audience?
As to screen shots, when I upload the IWSS.INF book here to Compuserve, every
screen that the product produces is included, this has had the effect of
adding hundreds of megabytes to the size of the INF, hence there will be two,
one with, and one without, such that folks can download the little one, and
get a flavor of what the product does at little cost, if there is further
interest, they can then download the monster. I see this as helping in a
couple of ways.
1. informed purchase by the consumer. Such that I am attempting to alleviate
posts on the online services of "I didn't know that this product acted in this
ridiculous fashion".
2. informed purchase by the customer. If they see the ENTIRE product prior to
purchase, I hope they will know whether it fits thier needs or not. This
should reduce thier expense and mine.
So my thesis is, show the online information to any and all that desire to
see the product. Talk about what it does, and DOES NOT do, and proceed from
that point.
My greatest fear at this point is that the product is too technical, only
time will tell.
Jay Ice
Iceware Inc.
#: 69520 S20/Marketing OS/2 Apps
27-Dec-95 22:02:57
Sb: #69357-Documentation quality
Fm: Shmuel Metz (Atid/2) 71054,3066
To: Herbert Ice 72370,2501
IMHO, if you've taken the trouble to put together a manual for printing, you
should offer it preprinted and prebound, at a price commensurate with
production costs. This will save paper for the customer who doesn't have
duplex printers, and will save time.
I see softcopy as being of value in two situations.
If the softcopy is organized for a hypertext viewer like IPF, than it can
provide functionality that is unavailable in hardcopy. In particular, you
should have accessible help data for all of your error messages.
If the product is likely to be extensively tailored by the customer, than
revisable hardcopy allows the customer to tailor the documentation to suit his
installation.
Shmuel (Seymour J.) Metz, SysProg & JOAT, Atid/2, Team OS/2, Team PL/I
#: 69631 S20/Marketing OS/2 Apps
28-Dec-95 23:54:50
Sb: #69520-Documentation quality
Fm: Herbert Ice 72370,2501
To: Shmuel Metz (Atid/2) 71054,3066
Shmuel,
There will most definitly be a manual, there was never any doubt of that. I
was thinking of the spiral (plastic coated) bound manual. The purpose of a
softcopy version of the doc was to reduce the street price of the product. I
was not attempting to exclude the hardcopy, only to have a product that met
both sets of consumers needs. I have been told that the European market is
fairly sensitive to the shipping costs. Add in some VAT tax, etc. I also am
aware of this from personal experience of selling into Europe.
Jay Ice
Iceware Inc.
#: 69357 S20/Marketing OS/2 Apps
25-Dec-95 23:28:29
Sb: #69344-Documentation quality
Fm: Herbert Ice 72370,2501
To: Esther Schindler [EXEC] 72241,1417
Esther,
Let me say first off, that I do believe in documentation, having waded
through IBM 370, 4341, 390 PoPs I know good doc when I see it<g>, of course
that does not mean that I can write it(unforunatly).
Personally I would not consider a software product unless it had both online,
and hardcopy doc, as I do believe in the power of the john<g>. Most of my
question really centers around, "does the documentation have to arrive in a
hardcopy with the package, or can it arrive in a fashion that the consumer can
print it out as they see fit?
Actually I think the documentation stinks for most products, whether OS/2 or
not. I will have to defend IBM documentation (mainframe), in that the PoPs I
always found to be very good, although I would imagine that came from years of
experience. I also think that the documentation that comes with Rexx for the
VM enviroment is the best I have ever seen, in that it proceeds in 3 phases,
where you go through the users manual 3 different times, building upon what
was done the prior pass for that particular chapter. This does not restrict
you from reading cover to cover, but following the manual helps unfold Rexx
like peeling an onion. Or if you will the way most of us learn, I think.
Unfortunatly, our product does not have this capability ( in some areas it
does) of progressive learning, one must comprehend it all, or nothing.
Fortunatly this is limited to the IDE, SCSI, and PCI sections. For those
sections I do not want to just retype the relevant tech. spec. (besides
copyright problems). This is an area that I have wrestled with quite a bit. I
seam to be able to explain to customers over the phone what certain portions
of the SCSI spec mean to them, and thier business, so I have defaulted to
typing in the first person in that section of the online doc. Do you feel that
is appropriate?
I would agree that the person writing the code is too close to the product,
to write decent documentation, alas in my case this will have to be done for
the first go around. Then pass the doc through a technical writer ( I know a
fine tech writer back in VA) for the second pass. As in my experience, I can
get the technical parts down, but the tech writer, raises questions that I
would never think of.
When you refer to "here's the basics", the first question I have coming back
to you is, "How basic is basic?". Let's take the area of hard drive
performance (in certain area's I am about to give up on basics, such as the
Process Information), does one have to start at the "This is a track, This is
a head, they comprise a cylynder ..." level. Or is this more a question of the
target audience?
As to screen shots, when I upload the IWSS.INF book here to Compuserve, every
screen that the product produces is included, this has had the effect of
adding hundreds of megabytes to the size of the INF, hence there will be two,
one with, and one without, such that folks can download the little one, and
get a flavor of what the product does at little cost, if there is further
interest, they can then download the monster. I see this as helping in a
couple of ways.
1. informed purchase by the consumer. Such that I am attempting to alleviate
posts on the online services of "I didn't know that this product acted in this
ridiculous fashion".
2. informed purchase by the customer. If they see the ENTIRE product prior to
purchase, I hope they will know whether it fits thier needs or not. This
should reduce thier expense and mine.
So my thesis is, show the online information to any and all that desire to
see the product. Talk about what it does, and DOES NOT do, and proceed from
that point.
My greatest fear at this point is that the product is too technical, only
time will tell.
Jay Ice
Iceware Inc.
#: 69582 S20/Marketing OS/2 Apps
28-Dec-95 14:00:19
Sb: #69357-#Documentation quality
Fm: Steve Pitts 100331,1134
To: Herbert Ice 72370,2501 (X)
Herbert,
> does the documentation have to arrive in a hardcopy with the package, or can
it arrive in a fashion that the consumer can print it out as they see fit? <
If you are going to have docs that are designed to be read away from the
machine (and there are products which require little more than installation
instructions in a printed form, although they are few and far between. Whether
or not yours fits that category only you can tell) then they need to be
provided in a suitable hardcopy format (ie. sturdy, long lasting and able to
lay flat on a desk without having the rock of Gibraltar perched on top of them
to hold them open <g>). Providing a file that can be printed may be fine for
evaluation copies of SW but once I've paid for it I expect better.
The online documentation should take advantage of the product being used to
display it (ie. IPF in OS/2 terms) and not simply be a machine readable copy
of the printed version.
> I will have to defend IBM documentation (mainframe), in that the PoPs I
always found to be very good <
But only once you know what you are doing :)
> I also think that the documentation that comes with Rexx for the VM
enviroment is the best I have ever seen <
Agreed. This was the first IBM manual that I ever recommended to anyone else
as a _good_ way to learn about an IBM product
Cheers, Steve
(Using OzCIS in Hemel Hempstead, England on 28-Dec-95 at 17:43:05)
There is 1 Reply.
#: 69616 S20/Marketing OS/2 Apps
28-Dec-95 21:06:55
Sb: #69582-Documentation quality
Fm: Herbert Ice 72370,2501
To: Steve Pitts 100331,1134
Steve,
Thanks for the input, as to PoP, I don't agree that was my bible when
learning assembler.
Jay Ice
Iceware Inc.
#: 69676 S20/Marketing OS/2 Apps
29-Dec-95 15:34:40
Sb: #69616-#Documentation quality
Fm: Steve Pitts 100331,1134
To: Herbert Ice 72370,2501 (X)
Herbert,
> as to PoP, I don't agree that was my bible when learning assembler. <
But were you sat down in front of a copy and told, here's the manual, learn
assembler?? The POP is a great reference work, and a useful adjunct to the
learning experience, but I'd hate to learn assembler with nothing else to
guide me
Cheers, Steve
(Using OzCIS in Hemel Hempstead, England on 29-Dec-95 at 20:30:05)
There is 1 Reply.
#: 69726 S20/Marketing OS/2 Apps
30-Dec-95 00:55:37
Sb: #69676-Documentation quality
Fm: Herbert Ice 72370,2501
To: Steve Pitts 100331,1134 (X)
Steve,
> But were you sat down in front of a copy and told, here's the
> manual, learn assembler??
Correct, I had progressed into writing system mods for VM by the time I took
my fist 370 assembly class.
Jay Ice
Iceware Inc.
#: 69407 S20/Marketing OS/2 Apps
26-Dec-95 14:19:38
Sb: #69386-#Documentation quality
Fm: Guy Scharf [Sysop] 76702,557
To: Esther Schindler [EXEC] 72241,1417 (X)
Esther,
Speaking entirely as a user, I have a pet peeve about printing user manuals.
First, I don't like to do it. A manual printed on 8.5x11 paper looseleaf is
more unwieldy than a perfect-bound, smaller-sized manual.
But, more importantly, I have generally not be able to get the manuals to
print double sided, which uses 2x as much paper as it needs to. I *do* have a
duplex printer, and one of my purposes is to save paper. Yes, I suppose if I
knew PostScript I might be able to figure out how to edit it to use the duplex
feature, but that really shouldn't be required of the user.
As a user, I want the manual both in printed form *and* online! And I want
both of them to be complete. Online is very useful for reference material and
looking things up while I am working on the computer; printed is essential for
study and for learning a product. All of the vendors I have seen who have
opted for electronic manuals only seem to speak to the needs of the
established customer and are raising the barrier for the new customer by
making their product more difficult to use than it need be.
Case in point: Quicken for Windows Deluxe version. The diskette version has
printed manuals. The CD-ROM version has more information on the CD-ROM but
lacks printed manuals. I want the additional features, and I also want the
printed manuals. The fact that I can't get both in one box has delayed my
purchase by months, and may delay it indefinitely as I decide the previous
version continues to meet my needs well.
Guy
There is 1 Reply.
#: 69705 S20/Marketing OS/2 Apps
29-Dec-95 22:28:23
Sb: #69407-#Documentation quality
Fm: Buck Bohac 70670,2352
To: Guy Scharf [Sysop] 76702,557
Hi Guy,
> <<Esther nods enthusiastically, in agreement>>
<<Buck nods enthusiastically, in agreement as well.>>
One more thing while we're on the documentation issue. Although screen shots
can be helpful, what really irks me is when I click on the help button in a
dialog box and I get a help screen with a picture of dialog box and some text
that says "click on the OK button to select the option, click on the CANCEL
button to go back, and click on the HELP button for help". I want to know
what the consequences are for clicking on OK. Why is this dialog important?
What is the definition of these terms that I don't understand? Etc., etc.,
etc. If you're going to go to the trouble of giving me some information, at
least give me something useful. The worst offender is probably IBM.
Also, I want lots of examples, sample situations, code snippets, etc.
Buck
There is 1 Reply.
#: 69719 S20/Marketing OS/2 Apps
29-Dec-95 23:46:23
Sb: #69705-Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Buck Bohac 70670,2352
Yes, yes, examples! Sample situations! Pictures of the owner's dog! Humor!
<<Esther begins to drool>>
(Hmm. Maybe I've been working too hard. I guess it'd help if that dratted %#*@
program I'm supposed to be reviewing would actually _work_...)
--Esther
#: 69509 S20/Marketing OS/2 Apps
27-Dec-95 20:29:26
Sb: #69477-Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Herbert Ice 72370,2501
I think you're still being unclear about who will buy your product. The answer
could be as simple as, "The same people who purchase Gammatech Utilities or
Partition Magic" (in which case you find yourself with a _really_ good clue
about partnering for effective cooperative marketing), or as complex as
"Anyone who needs to manage or maintain OS/2 systems to the peak of their
performance."
In other words, I'm trying to get you to define, explicitly, who will USE your
program.
The second step is to define who will _buy_ the product which (as can be
easily demonstrated in a corporate environment) might be a very different
answer.
You're going to start out with power users. EVERYONE starts out with the early
adopters... or they wouldn't be called early adopters, now would they? <grin>
So design your message to appeal to them (the people who own _lots_ of
screwdrivers, not to mention a model train set, a complex kitchen gadget, and
a ham radio setup), but keep in mind that the eventual audience is much
bigger.
Norton Utilities' marketing really is a good model for you; originally it was
for the techies, but eventually it was marketed as the *lifesaver,* the tool
to have around if you're afraid of what could happen. I'm sure that plenty of
packages were purchased and never used, like kitchen fire extinguishers. But
notice the distinction between the early market (people who liked to muck
about with their boot records), the mainstream market (people who want the
security of a spare tire in the trunk) to the eventual use with the laggards
(subset of utilities bundled with the OS and thus invisible to the user).
> to distill it down to 3 shots, somehow feels like cutting the
> products throat
Jay, you _must_ find a way to do this. If for no other reason, if *you* don't
find a way to express the product's purpose in two sentences or less (and 3
screen shots or less) than other people will. A good part of what PR is really
about is defining the message you want people to get in their heads about your
company and your product. If you don't create an image, others will create it
for you... and that image might or might not be one that you'd choose.
Your first effort was good (though I rarely show the opening screen for
anything <grin>). Now improve it. <smile>
--Esther
#: 69754 S20/Marketing OS/2 Apps
30-Dec-95 13:49:13
Sb: #69509-#Documentation quality
Fm: Charles Stirling 100010,1433
To: Esther Schindler [EXEC] 72241,1417 (X)
Hi,
I am not a developer, just a user, and had planed on just lurking here. Must
be a busybody as well as I can't just lurk, want to see OS/2 stuff sold.
The comment "Anyone who needs to manage or maintain OS/2 systems to the peak
of their performance" aims the product to high and excludes to many potential
purchasers. I think you need to aim more at where Norton Utilities'
Quarterdeck Manifest ended up aiming -- not the power user but the concerned
user with the power user included. Instead of "... to the peak of their
performance" to "... improve performance". This would not put the middle
ground person as they could get something out of it and descover more.
On documentation, it almost sounds like two manuals are needed. The 200+ page
one that gives all the depth might be OK for me even as a zip file on disk as
the technical referance. A printed one that gives, as Esther has pointed out,
from the very basic, including what can be done, to the general usage maybe
with side notes to the more technical manual as tips in the margin. Yes, a
printed technical manual would be preferable, but cost comes into this also.
What does it cost for a print run of say 2000 copies, 5000 copies of 200+
pages plus the extra postage to send say to me in England.
Charles
There is 1 Reply.
#: 69769 S20/Marketing OS/2 Apps
30-Dec-95 20:12:34
Sb: #69754-Documentation quality
Fm: Herbert Ice 72370,2501
To: Charles Stirling 100010,1433
Charles,
PMFJI,
> The comment "Anyone who needs to manage or maintain OS/2 systems
> to the peak of their performance" aims the product to high and
> excludes to many potential purchasers.
I would agree if the product was intended try to sell thousands per day, from
day one, say like windos95<G>, seems it missed the hyped mark though<VBG>.
Esther and yourself, have split the market into three sections, technical,
power/concerned, and the tail end. At this juncture, the technical market
seems the better place to me, for the following reasons,
1. Customer support will be reduced, as in general when dealing with the
corporate/technical market, there is in general one point of contact (while it
may be one point per site, that still is better than thousands). While of
course everyone that purchases a given product does not call, even a small
percentage (5->10) can be very difficult to provide decent service to.
2. The feedback on the technical side I feel will be of higher quality, those
things which I missed, those things I thought to be not importent but which
the customer does feel is importent. Then will come the layout of the data,
screens etc. to a lessor degree.
3. When the power user begins to purchase, this group I expect will focus on
the technical side, but with a keener interest in the asthetics of the
product, which has to happen.
4. In order to appeal to the mass market, in order to have the online
services have the usage of "cool"/"kewl". etc.
I may have the wrong plan in my head but I see a staged rollout of the
product, much as Esther alluded too with Norton Utilities.
Documentation,
Splitting into two seperate documents is a fine idea, along with having a
quick reference card. Quick refs are not expensive (7 panel, heavy stock,
generally hits around a $1 a ref), and the customer bases that I have dealt
with seem to appreciate them quite a bit, consultants in particular like to
have two in the package, one for the briefcase, one for the workplace. Nor do
they add significantly to shipping wieght.
For a decent quality paper ( 20# bond, matte finish, so that it does have
glare under flourescent light, heavy stock for front and back, and plastic
spiral bound so that it will lay flat), I have been quoted in the Reston VA.
area as high as $800 for 100 copies not to exceed 75 pages. The reason that
the quantity was so low, was due to I have no idea how well the product will
sell, and during my years in development, I have seen hundreds of thousands of
dollars in doc pitched. I also expect that there will have to be a fairly
quick update to the product after ship in order to meet certain users
expectations, and this always leads to invalidating the documentation that one
currently has.
Jay Ice
Iceware Inc.
#: 69443 S20/Marketing OS/2 Apps
26-Dec-95 22:49:45
Sb: #69426-#Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Felix Cruz 72274,3102 (X)
Early adopters like us pride ourselves on the fact that we've never read the
manual. Ordinary users *do* read them... and are usually confused.
Apropos of this whole discussion, my next door neighbor (the one who bought a
home computer a year ago "so I could start to do some writing") called me
yesterday afternoon to ask me to help her install Myst. The short version of
the problem was that she didn't know how to tell windows "E:\setup.exe" --
because the manual said X:SETUP.EXE, and she sure didn't have an X drive. It
did say to substitute the CD ROM driver letter for X, but she didn't know the
CD ROM drive even *had* a drive letter, or what one was.
I talk to these people because they keep me honest. I'll rent Michelle to you,
anytime you need the same experience. <grin> (She's nice, she's pretty, she's
divorced... she has 4 kids...)
--Esther
There is 1 Reply.
#: 69782 S20/Marketing OS/2 Apps
30-Dec-95 21:26:16
Sb: #69443-#Documentation quality
Fm: Shmuel Metz (Atid/2) 71054,3066
To: Esther Schindler [EXEC] 72241,1417 (X)
>> Early adopters like us pride ourselves on the fact that we've never read
the manual. Ordinary users *do* read them... and are usually confused. <<
My experience is just the opposite. The ordinary users are the ones that don't
read the manuals unless they have to, and sometimes not even then.
Admittedly there are a lot of programmers who hate the read manuals, but the
ones that I respect are all voracious readers. Coincidence? Perhaps, but I
don't believe it.
Of course, sometimes you flat don't have time to read everything that you want
to (or need to), but that's a separate issue.
Shmuel (Seymour J.) Metz, SysProg & JOAT, Atid/2, Team OS/2, Team PL/I
There is 1 Reply.
#: 69784 S20/Marketing OS/2 Apps
30-Dec-95 21:58:29
Sb: #69782-Documentation quality
Fm: Esther Schindler [EXEC] 72241,1417
To: Shmuel Metz (Atid/2) 71054,3066
It depends on the nature of the "ordinary" user, and the training that the
user was given.
Most people who want to be experts (in whatever field they choose) are
voracious readers, or at the least voracious learners. (These are generally
intersecting sets, but not always.) People do learn differently; some learn
from a book, others learn by watching someone do it, etc. The manual writer
can't change that, but at the very least she has to write the manual *as if*
someone will try to learn everything about the product from it, and *as if*
it's the primary source of knowledge.
I rarely classify programmers as "ordinary users." ;-)
--Esther
#: 69501 S20/Marketing OS/2 Apps
27-Dec-95 19:27:46
Sb: #69499-Documentation quality
Fm: Jon Duringer[IdeaFa 71732,3361
To: Samuel G. Little 70544,10
>> I doubt this will ever occur, Jon.
Let me put my thought this way. Suppose documenting software products became
absolutely illegal and impossible. Would the software industry disappear?
No, we'd just be forced to fully exploit SOM and OS/2 to create simple,
visually intuitive objects which corresponded closely to physical objects that
everyone is familiar with. The objects would need to be safe, intriguing, and
indestructable, kind of like the objects that we give to 2 year old toddlers.
The objects would have to do interesting things when manipulated in simple,
general ways. The software industry wouldn't disappear, but it -would- be
radically transformed.
Samuel, this is where we need to go to eliminate Moore's Chasm. With OS/2, we
-can- do this. Let's set our sights on it, and spend the next 10 years
getting there.
In the short term, we do need to write better documentation. In the longer
term, we need to start thinking about eliminating the need for documentation
altogther, to make our products like crayons, pads of paper, and staplers.
#: 69783 S20/Marketing OS/2 Apps
30-Dec-95 21:26:23
Sb: #69501-Documentation quality
Fm: Shmuel Metz (Atid/2) 71054,3066
To: Jon Duringer[IdeaFa 71732,3361 (X)
>> The objects would need to be safe, intriguing, and indestructable, kind of
like the objects that we give to 2 year old toddlers. <<
I'd hate to have to repair a car or a computer using only tools suitable for a
toddler!
Shmuel (Seymour J.) Metz, SysProg & JOAT, Atid/2, Team OS/2, Team PL/I