"They don't need no stinkin' documentation..."
Melissa Lowery
Here's an excerpt from Monday's Shark Tank:
IT MANAGER pilot fish finds lots of information missing from the new
documentation for a key project. Where is it? he asks. Developer
responds: "I've found that most people in our field are overwhelmed
by too much documentation. I found that, by removing the parts that
everyone already knows, I could make a more artistic presentation."
_____________________________________________________________
Can't get enough Tank?
Check out other bite-sized bits of humor, rumors, gossip and fun at The
Sharkives:
http://www.computerworld.com/cwi/sharktank/0,1130,NAV47-68-86-103,00.htm
l
_____________________________________________________________
So this little tidbit shows that the non-techie technical writers who
are trying to avoid actual writing (a common A. Plato strawman) might
not be the only ones concerned about the "artistic beauty" of their
prose!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.
For details and online registration, visit http://ieeepcs.org/2001
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ej...@raycomm.com) for details and availability.
---
You are currently subscribed to techwr-l as: tech...@GTS.ORG
To unsubscribe send a blank email to leave-tech...@lists.raycomm.com
Send administrative questions to ej...@raycomm.com. Visit
http://www.raycomm.com/techwhirl/ for more resources and info.
Tom Murrell
|
| So this little tidbit shows that the non-techie technical writers who
| are trying to avoid actual writing (a common A. Plato strawman) might
| not be the only ones concerned about the "artistic beauty" of their
| prose!
You know, I'm not normally a defender of A. Plato, but I've never known him to
stick up for an idiot developer any more than he would stick up for an idiot
writer.
Frankly, deliver us from ANYONE concerned about the "artistic beauty" of
technical documentation at the expense of solid, useable information.
=====
Tom Murrell
Lead Technical Writer
Alliance Data Systems
Columbus, Ohio
mailto:tmur...@columbus.rr.com
Personal Web Page - http://home.columbus.rr.com/murrell/
Page Last Updated 07/15/01
__________________________________________________
Do You Yahoo!?
Make a great connection at Yahoo! Personals.
http://personals.yahoo.com
Dick Margulis
Tom Murrell wrote:
|
|Frankly, deliver us from ANYONE concerned about the "artistic beauty" of
|technical documentation at the expense of solid, useable information.
|
Can we get rid of THIS strawman once and for all? It isn't either-or.
It's develop sufficient skills or collaborate with people with
complementary skills so that the documents we produce are BOTH chock
full of solid, usable information AND attractively designed so they are
inviting to read. You can only fill a barrel to the height of its
shortest stave.
Dick
Iggy
| "artistic beauty" of
| technical documentation at the expense of solid,
| useable information.
Now them's words to live by.
Bruce Byfield
| Can we get rid of THIS strawman once and for all? It isn't either-or.
| It's develop sufficient skills or collaborate with people with
| complementary skills so that the documents we produce are BOTH chock
| full of solid, usable information AND attractively designed so they
| are inviting to read. You can only fill a barrel to the height of its
| shortest stave.
What, and rob everyone of their favorite rhetorical stance?
Personally, I'd just as soon everyone didn't understand that what you
say is true. This lack of understanding is keeping me employed. I'm no
Jan Tschichold, and, for that matter, I'm no Charles Dickens, but
**any** ability to combine both design and writing is so rare that
clients are glad to see it - even the ones who say that they don't care
about the design.
--
Bruce Byfield 604.421.7177 bbyf...@axionet.com
"What will I say when my children ask me,
'Where were you flying on that day?'
With trembling voice, I gave the order
To the bombadier of Enola Gay."
-Utah Phillips, "Enola Gay"
Andrew Plato
| Can we get rid of THIS strawman once and for all? It isn't either-or.
| It's develop sufficient skills or collaborate with people with
| complementary skills so that the documents we produce are BOTH chock
| full of solid, usable information AND attractively designed so they are
| inviting to read. You can only fill a barrel to the height of its
| shortest stave.
It isn't a stawman argument and it isn't a balencing act. Its a matter of
priorities. Too many writers put atheistics and format ahead of substance.
Yes, it is preferable to have documentation that looks nice, but never at
the expense of the information.
To invoke Plato's Law (as another TECHWR-L member once described it).
Bad content, bad format = Bad doc
Bad content, good format = Bad doc
Good content, good format = Good doc
Good content, bad format = Marginal doc
I don't care if you're documenting nuclear bombs or the latest Hello Kitty
toy - content should always be priority #1.
This same problem applies to virtually all professions, including
programmers and engineers. People who are more interested in the medium
and the method than the substance.
Andrew Plato
__________________________________________________
Do You Yahoo!?
Make a great connection at Yahoo! Personals.
http://personals.yahoo.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Bruce Byfield
|
|It isn't a stawman argument and it isn't a balencing act. Its a matter of
|priorities. Too many writers put atheistics and format ahead of substance.
|Yes, it is preferable to have documentation that looks nice, but never at
|the expense of the information.
|
It's a straw man because the Content Is King argument always frames the discussion as if design simply meant making everything pretty. Given Dick's contributions to the list over the year, I feel reasonably certain that he is talking about design that enhances readability and perhaps assists the client with corporate branding. Certainly, that's what I mean when I talk about design.
Yes, there are people who fiddle with fonts out of an obsession with novelty, or simply out of a wish to avoid serious work like learning what they are writing about. But that's not design - that's shirking.
As for priorities, I think I'll evoke the Universal Panacea for this list: it depends on the audience. If you're writing for stone techies, then you can get away with poor design. You're writing for a highly motivated audience who will expend the effort needed to overcome your shortcomings. I mean, people who will endure man pages will endure anything :-)
However, if you're writing for more casual users, then design could be the difference between them reading the documentation and walking away from all your hard work. It doesn't matter how good your content is if people can't or won't use it.
And, for that matter, even though stone techies are more likely to overlook bad design, that doesn't mean they like it. If the design lets them get their information and get on with whatever they're doing, they're as pleased as anyone. After all, just because you can lift 500 pounds doesn't mean that you want to do so a dozen times a day.
--
Bruce Byfield 604.421.7177 bbyf...@axionet.com
"What will I say when my children ask me,
'Where were you flying on that day?'
With trembling voice, I gave the order
To the bombadier of Enola Gay."
-Utah Phillips, "Enola Gay"
david...@amd.com
|However, if you're writing for more casual users, then design could be the difference
|between them reading the documentation and walking away from all your hard work. It
|doesn't matter how good your content is if people can't or won't use it.
These days the biggest issue in the PC industry is how do we get phobic to use PCs and PC software. These people will not endure man pages. They will not tolerate what they feel is poor documentation. They are not motivated to learn or to wait. They don't want controls. They want to do their work. They don't want to do something, because the software insists on it. They insist on design.
Their insistence on design extends beyond manuals and help. They want the software tasks to be allocated to the software. They want to focus entirely on tasks from the automated domain, not the automation. They want defaults and power without all the feature bloating controls. They want embedded. They want a picture or a table that cuts a thousand words. They want a view, not a black box.
Sure the market for technical enthusiast technology will always be there, and a lot of us serve that market. But, the markets and audiences after that one still need good content, but the content changes and eventually, in phobic markets, better disappear almost completely.
When was the last time you set the top-end limit of your car's performance? Not lately. For the most part, you go out, buy a new chip, and pull out the old one, and press the new one into the socket. You need two pictures: one that shows you where the socket is and, another to show how the chip is oriented in the socket. You might need a few words about disconnecting the battery, applying heat sink, and not abusing the chip as you snap it into place. There is a lot of technology there, but it's embedded.
David Locke
Andrew Plato
| As for priorities, I think I'll evoke the Universal Panacea for this
| list: it depends on the audience. If you're writing for stone techies,
| then you can get away with poor design. You're writing for a highly
| motivated audience who will expend the effort needed to overcome your
| shortcomings. I mean, people who will endure man pages will endure
| anything :-)
Yeah, but the "it depends" argument falls off at a base level. If you
don't have your content ducks in a row, it doesn't matter if you're
documenting pulsars for Stephen Hawking or Pokemon diapers for illiterate
crackheads. The part that truly matters is the information. Everything
else is dressing. It might be important dressing - but it can never
overtake the value of the information.
Andrew Plato
__________________________________________________
Do You Yahoo!?
Make a great connection at Yahoo! Personals.
http://personals.yahoo.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Andrew Plato
| Their insistence on design extends beyond manuals and help.
| They want the software tasks to be allocated to the software.
| They want to focus entirely on tasks from the automated domain,
| not the automation. They want defaults and power without all
| the feature bloating controls. They want embedded. They
| want a picture or a table that cuts a thousand words. They
| want a view, not a black box.
Yeah, yeah...those damn users. They want software that installs itself,
never fails, reads their mind, and can operate flawlessly at
faster-than-light speeds while running on a grain of sand floating in a
pool of molten lead. Sorry, its in beta right now. Wait for the Service
Pack.
I agree - people want easy. But when it comes to docs, part of making it
easy is knowing what to say and what not to say. And if you expect to do
that with any degree of skill, you had better know what it is you're
saying - otherwise, you won't say much at all. And that's worse.
| When was the last time you set the top-end limit of your car's
performance?
While the average joe might not, its the people who do push performance
that set the market demands. If everybody was comfortable with 640K
286-16s running DOS we would never have seen any improvement. The drive to
improve and push performance and capability is the central motivating
force of any expanding market.
Of course, I test the top-end limit of my car's performance pretty much
every day. So, if you see two blinding oval Xenon headlights and an Oregon
license plate that reads "APLATO" coming at you - get outta the way. I'm
late for a meeting. :-)
Sabahat Ashraf
| Frankly, deliver us from ANYONE concerned about the "artistic beauty" of
| technical documentation at the expense of solid, useable information.
Ah, the beauty of solid, usable information ....<g,d,r>
<from a safe distance>Sorry; that was too tempting...
SIA
Jim Shaeffer
| else is dressing. It might be important dressing - but it can never
| overtake the value of the information.
|
| Andrew Plato
But, there are fascinating reports of users who discarded solid
technical documentation because it looked too good. They dismissed
it as 'marketing fluff' without bothering to read it.
Jim Shaeffer (ji...@spsi.com)
Susan Guttman
That one's good, but my all-time favorite Shark Tank documentation story is
this one:
Did you receive the instructions? fish asks.
Affirmative.
Did you read them?
Yes, says sysadmin, getting testy.
Did you follow the instructions? fish asks.
"Your instructions don't say that you have to follow the instructions,"
sysadmin snarls.
http://computerworld.com/cwi/sharktank/0,1130,DAY10-15-2001_NAV47-2057_STO64
833,00.html
-----Message d'origine-----
Melissa Lowery wrote:
or "Why we don't let developers do the documentation..."
Here's an excerpt from Monday's Shark Tank:
IT MANAGER pilot fish finds lots of information missing from the new
documentation for a key project. Where is it? he asks. Developer
responds: "I've found that most people in our field are overwhelmed
by too much documentation. I found that, by removing the parts that
everyone already knows, I could make a more artistic presentation."
Dick Margulis
|
|But, there are fascinating reports of users who discarded solid
|technical documentation because it looked too good. They dismissed
|it as 'marketing fluff' without bothering to read it.
|
|Jim Shaeffer (ji...@spsi.com)
jgar...@ide.com
writing world. He had a list of documentation "rules" ... two of my
favorites (that I still use!) are:
Truth doesn't stick to glossy paper.
Rule Zero: Have something to say.
John
Annamarie Pluhar
|
|These days the biggest issue in the PC industry is how do we get
|phobic to use PCs and PC software. These people will not endure man
|pages. They will not tolerate what they feel is poor documentation.
|They are not motivated to learn or to wait. They don't want
|controls. They want to do their work. They don't want to do
|something, because the software insists on it. They insist on design.
|
|Their insistence on design extends beyond manuals and help. They
|want the software tasks to be allocated to the software. They want
|to focus entirely on tasks from the automated domain, not the
|automation. They want defaults and power without all the feature
|bloating controls. They want embedded. They want a picture or a
|table that cuts a thousand words. They want a view, not a black box.
|
|Sure the market for technical enthusiast technology will always be
|there, and a lot of us serve that market. But, the markets and
|audiences after that one still need good content, but the content
|changes and eventually, in phobic markets, better disappear almost
|completely.
|
Hello all,
I'm amused by this thread and generally agree that content is first
and that design should aid the ability of the reader to obtain the
information that they need.
But David's comment above puzzles me, and indicates that there are
many different audiences for technical documentation. PC phobic?
Unlikely to even pick up the technical documentation. In that case
the user needs training, not documentation. That's my job as an
instructional designer. It all depends on the audience. I can think
of some businesses where "pretty" would be welcomed as
"user-friendly" - (Hallmark Cards?) and others where it would be seen
as frivolous. (KMPG)
Everything that David talks about in the first two paragraphs I would
consider to be issues that should be addressed by training, carefully
designed to suit the audience. After training users should have some
well designed, useful Job Aids to have at their desk.
I've always assumed that technical documentation served the
non-phobic users who understand that they'll get more out of the
software if they read about it.
I guess I've stopped lurking.
Annamarie
--
Annamarie Pluhar
IDD Tech Solutions
Instructional design and development for technology.
(301) 588 - 4001
(301) 646 - 5002 (Mobile)
www.iddtechsolutions.com
apl...@idd-solutions.com
Silver Spring, MD
SIA...@visus.jnj.com
Andrew Plato says:
'Content takes priority to design (function before form)'
Bruce Byfield says:
'Yes, content takes priority; yet design is important, as it will
affect audience response.'
Andrew Plato later reiterates:
'Yes, design is important, but content takes priority.'
You're actually arguing non-conflicting points: Andrew is arguing that
content takes priority [point 1], and Bruce is arguing that design is
important [point 2]. These points are not mutually exclusive, as you both
have agreed in your posts.
The heat that sets fire to the strawman seems to be that Point 1 proponents
infer that Point 2 proponents are claiming content does not take priority,
while Point 2 proponents infer that Point 1 proponents are claiming design
is unimportant. In both cases, the inference is wrong, and a result of
faulty logic.
So, does the continuation of the banter imply that it is actually a
thinly-disguised plot for imposing an exercise program on those needing to
tone their argumentation muscles? (who can be most easily identified by the
abusive tones their arguments inevitably display) :)
...actually, that brings up a question I have been curious about: while it
is established (at least academically) that expository writing and
argumentative writing are different animals, I'm curious whether you have
found that training in the subjects of logic, propaganda and debate have
improved the quality of your technical writing. If so, how? If not, why?
In my case, I believe it has helped. By playing "devil's advocate" with my
docs, and arguing with the proof of function they are supposed to provide
(these are primarily design docs and testing docs, not user docs), I am
able to identify gaps faster (I am a lone tech writer with no established
review process in my department, so I must catch everything myself). I have
found the skills even more useful in dealing with initially recalcitrant
SMEs.
What have you found?
Shauna Iannone
Bruce Byfield
|Bruce Byfield says:
| 'Yes, content takes priority; yet design is important, as it will
|affect audience response.'
|
No, I'm agreeing with Dick's original statement that effective
documentation is a balance of content and design. Ask me to choose one
over the other, and you're going to hear a lot of stuttering, because I
don't see how you can separate one from the other.
However, what the discussion has ignored so far is that tech-writing has
all sorts of niches. I've happened to find one in which design is a
selling point for my services. Andrew has found other niches in which
design doesn't matter so much.
--
Bruce Byfield 604.421.7177 bbyf...@axionet.com
"What will I say when my children ask me,
'Where were you flying on that day?'
With trembling voice, I gave the order
To the bombadier of Enola Gay."
-Utah Phillips, "Enola Gay"
david...@amd.com
| needs. That is not good design. Good design is design that suits its purpose. If the
| purpose is to be read, the design should support that. "Looked too good"? No. Looked
| too pretty, maybe.
Absolutely. If you look at a table and see what you need to see immediately, you won't even think about how many hours it took to make that happen. You won't know that the SME created four tables with different relationships, that the source tables couldn't just be dropped in and lined up into that one table. All you will know is that you didn't have to kill yourself to get the answer. It was right there. That's design. That's content.
David Locke
Bruce Byfield
|
|Yeah, but the "it depends" argument falls off at a base level. If you
|don't have your content ducks in a row, it doesn't matter if you're
|documenting pulsars for Stephen Hawking or Pokemon diapers for illiterate
|crackheads. The part that truly matters is the information. Everything
|else is dressing. It might be important dressing - but it can never
|overtake the value of the information.
|
Contrariwise, you can understand your topic forward, backwards, and sideways, and as seen through the fifth dimension, but if people can't or won't use the content effectively, they might as well not have it. That's why content and design have equal importance to me: they both have to be good if the information is going to be delivered.
I'd make an analogy to movies. Under the auteur theory of movies that's so widespread today, the producer gets all the credit for a movie's success. However, as William Goldman points out, for a movie to work, not only the producer, but also the writers, the actors, the camera crew, and the editors also have to be at their best. Unless all the different parts are coordinated, the whole won't amount to much.
--
Bruce Byfield 604.421.7177 bbyf...@axionet.com
"What will I say when my children ask me,
'Where were you flying on that day?'
With trembling voice, I gave the order
To the bombadier of Enola Gay."
-Utah Phillips, "Enola Gay"
Sandy Harris
|
| "Bruce Byfield" wrote...
|
| > As for priorities, I think I'll evoke the Universal Panacea for this
|
| Yeah, but the "it depends" argument falls off at a base level. If you
| don't have your content ducks in a row, it doesn't matter if you're
| documenting pulsars for Stephen Hawking or Pokemon diapers for illiterate
| crackheads. The part that truly matters is the information. Everything
| else is dressing. It might be important dressing - but it can never
| overtake the value of the information.
Granted, the first requirement is to know what you're talking about. If
you don't have that, you cannot document well for any audience.
However, given that, I think you're looking at three essentials for what
you actually put in the docs -- technical accuracy, suitability for the
audience and decent organisation. Miss any of the three and you've blown
it, usually fatally.
Technical accuracy I won't argue. We need it, period. One nice thing is
that it is moderately easy to check in most organisations. If you can
get your developers (SMEs, whatever) to review docs at all, and keep
them focused on content, they can help a lot here.
Audience analysis is also vital. For experienced system admins, I can
just say "set up a non-routable subnet on eth0". That's a perfectly
adequate description of a task they can do in their sleep. For another
audience, you'd need pages of explanation, procedures, examples, ...
You cannot even evaluate whether your doc is complete without some
fairly clear notion of the audience.
Note that developers often cannot help much here. Marketing or tech
support or quality control may.
Finally, there's organisation. As I see it, this is where most of us
give most of our "value added". A document could contain all the
right information, at the right level for the audience, but still be
almost entirely useless if it is hard to read and harder to find
things in.
A lot of this is global stuff. How do I structure the document?
How do I handle basic information many readers will already
know, but that needs to be there for some? A glossary? Side text
boxes? Footnotes? References to other sources? Web links?
A lot of it, though, is low-level detail.
Do I explain this with an example? An analogy? An exposition of
the theory behind it? Several of those?
Which terms need to be in the index? How about synonyms for this
audience?
Is this clearer as a paragraph of text? A list? A table?
What combinations of fonts, indentation and perhaps header/footer
usage makes my headings easily searched?
I agree that obsessing about things on that level without first
getting the really crucial stuff right is fatal.
However, I cannot agree that content == crucial stuff. Methinks
matching the audience and overall organisation are also vital.
Dugas, Andrew
I don't know where Andrew is going with this, but let's keep religious
beliefs (or intentional lack thereof) out of this.
-----Original Message-----
From: Andrew Plato [mailto:intre...@yahoo.com]
Sent: Monday, October 29, 2001 7:48 PM
To: TECHWR-L
Subject: Re: "They don't need no stinkin' documentation..."
| Can we get rid of THIS strawman once and for all? It isn't either-or.
| It's develop sufficient skills or collaborate with people with
| complementary skills so that the documents we produce are BOTH chock
| full of solid, usable information AND attractively designed so they are
| inviting to read. You can only fill a barrel to the height of its
| shortest stave.
It isn't a stawman argument and it isn't a balencing act. Its a matter of
priorities.
Yes, it is preferable to have documentation that looks nice, but never at
the expense of the information.
To invoke Plato's Law (as another TECHWR-L member once described it).
Bad content, bad format = Bad doc
Bad content, good format = Bad doc
Good content, good format = Good doc
Good content, bad format = Marginal doc
I don't care if you're documenting nuclear bombs or the latest Hello Kitty
toy - content should always be priority #1.
This same problem applies to virtually all professions, including
programmers and engineers. People who are more interested in the medium
and the method than the substance.
Andrew Plato
Dugas, Andrew
the TW writing for illiterate crackheads.
First of all, does Nintendo merchandising specifically target illiterate
crackheads? What about literate ones? What about cokehead attorneys?
Clearly the first audience would require much more graphics than the second
or third. But wouldn't the same materials alienate the lawyer audience?
In short, how does the poor TW at Nintendo Merchandising write for such a
diverse audience?
All things considered (and this is just the tip of the iceberg) it sounds
much more challenging than documenting the pulsars.
-----Original Message-----
From: Andrew Plato [mailto:intre...@yahoo.com]
Sent: Monday, October 29, 2001 11:29 PM
To: TECHWR-L
Cc: TECHWR-L
Subject: Re: "They don't need no stinkin' documentation..."
.... it doesn't matter if you're documenting pulsars for Stephen Hawking or
Pokemon diapers for illiterate crackheads.
Andrew Plato
Douglas S. Bailey (AL)
| backwards, and sideways, and as seen through the fifth
| dimension, but if people can't or won't use the content
| effectively, they might as well not have it. That's why
| content and design have equal importance to me: they both
| have to be good if the information is going to be delivered.
Good point. It's important to have a strong military, but if we can't
deliver our "big hammer" to the target than it's not very dangerous, eh?
Content, like military might, is only as valuable as the design/delivery
system, and vice versa.
--Doug
Bruce Byfield
|However, given that, I think you're looking at three essentials for what
|you actually put in the docs -- technical accuracy, suitability for the
|audience and decent organisation. Miss any of the three and you've blown
|it, usually fatally.
|
This may just be a matter of parsing the process differently, but I'd
suggest that successful documentation depends on:
- gathering accurate and appropriate information.
- understanding the audience's needs and the circumstances of use.
- organizing the project.
- organizing the information.
- designing the template.
- writing the document.
- reviewing and editing.
- producing the final document (whether steering it through the print
house or preparing it for on-line use).
A major failure at any one of these stages can wreck the document.
--
Bruce Byfield 604.421.7177 bbyf...@axionet.com
"What will I say when my children ask me,
'Where were you flying on that day?'
With trembling voice, I gave the order
To the bombardier of Enola Gay."
-Utah Phillips, "Enola Gay"
Michele Marques
|
| However, if you're writing for more casual users, then design
| could be the difference between them reading the
| documentation and walking away from all your hard work. It
| won't use it.
|
But if the content is wrong, or leaves out important points so that the
reader can easily get the wrong impression or do dangerous things, then
having your document easy-to-use doesn't matter. It just means people will
find the wrong information faster, or will be more likely to use your docs
to get the wrong impression.
I do agree, however, that there is a point to design. And it is a strawman
to determine whether you should spend 100% effort on content vs 100% effort
on design.
It is more useful to ask at what point do you have enough accurate content
that you should spend some time on design.
For example, if you have 80% of the content written accurately, it might be
time to apply some basic design principles. Until you have all the content
in place, you shouldn't be spending lots of time on layout. But if you have
a document (perhaps you inherited lots of content) that has no headings, no
table of contents, and all procedural instructions are in long paragraphs
(that could be broken up into numbered steps), it might be time to make a
quick formatting pass and generating a table of contents.
If the design is so bad that only the truly desperate will read
documentation (and then only when Support is unavailable), then the last 20%
of content (assuming it is the least necessary 20%) might not be worth
making that 80% slightly easier to access.
If the design is really bad (as implied by Andrew's formula of "good content
+ bad design = marginal doc"), you could turn this into an adequate
document. A good document would have all the content in place and, perhaps,
further improved design. An excellent document would have great content and
great design.
- Michele
------------------------------------------------------------------------
Michele Marques, Technical Communicator
AUTROS Healthcare Solutions, Inc.
marq...@autros.com <mailto:marq...@autros.com>
This material is intended for the use of the individual
to whom it is addressed and may contain information that
is privileged, proprietary, confidential and exempt from
disclosure. If you are not the intended recipient or the
person responsible for delivering the material to the
intended recipient, you are notified that dissemination,
distribution or copying of this communication is strictly
prohibited.
If you have received this communication in error,
please contact the sender immediately via e-mail and destroy this message
accordingly.
Dick Margulis
|But if the content is wrong, or leaves out important points so that the
|reader can easily get the wrong impression or do dangerous things, then
|having your document easy-to-use doesn't matter. It just means people will
|find the wrong information faster, or will be more likely to use your docs
|to get the wrong impression.
I don't recall _anyone_ arguing to the contrary. That's why I called this a strawman in the first place.
|
|I do agree, however, that there is a point to design. And it is a strawman
|to determine whether you should spend 100% effort on content vs 100% effort
|on design.
|
|It is more useful to ask at what point do you have enough accurate content
|that you should spend some time on design.
Not particularly. That strikes me as a peculiar way to work in most cases. I think that typically it is more efficient to have a general structure in mind before starting to write--a basic outline of how you plan to approach the subject from the perspective of the audience.
I've worked on many projects where accurate information was chronologically the last element available. But when it finally was available, it fell into a prepared matrix with very little effort on my part.
|
|For example, if you have 80% of the content written accurately, it might be
|time to apply some basic design principles. Until you have all the content
|in place, you shouldn't be spending lots of time on layout. But if you have
|a document (perhaps you inherited lots of content) that has no headings, no
|table of contents, and all procedural instructions are in long paragraphs
|(that could be broken up into numbered steps), it might be time to make a
|quick formatting pass and generating a table of contents.
That kind of ad hoc design work is a huge waste of everyone's time. Plan first. Write second. Touch up the details if there is time at the end.
|
|If the design is so bad that only the truly desperate will read
|documentation (and then only when Support is unavailable), then the last 20%
|of content (assuming it is the least necessary 20%) might not be worth
|making that 80% slightly easier to access.
Huh?
|
|If the design is really bad (as implied by Andrew's formula of "good content
|+ bad design = marginal doc"), you could turn this into an adequate
|document. A good document would have all the content in place and, perhaps,
|further improved design. An excellent document would have great content and
|great design.
Great design is an admirable goal, but good, serviceable design should be a basic requirement.
Dick
Beilby, Margaret
a basic requirement.>>
Absolutely! When you take in basic readability/usability guidelines into
consideration, I think it's difficult to separate content and design. To
have a really good document, you have to have both.
Margaret Beilby
mbe...@ebuilt.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author! iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,00 retailers. Join our almost
10,000 published authors today. http://www.iuniverse.com/publish/default.asp
John Posada
taking awhile to wwork through 1800+ emails.
| by too much documentation. I found that, by removing the parts that
| everyone already knows, I could make a more artistic presentation."
Real story...
I crerated a user guide for an application being distributed to the
sales team. What with conventions, error messages, instructions,
etc., the guide ran 16 pages. The document included several pages of
what do do when something unexpecred happened because of database or
user error.
Another department took MY document and cut it down to 5 pages.
(Press this, that happens. Click that, this happens) An executive saw
both documents and declared that they other document was more
acceptable. The reason? it presented a better message.
What message? That the software was easier to use and not subject to
errors. As far as using the document to use the application...his
response: "How should I know...I don't have a login and password for
the application."
Who is using MY document? Yup, technical support and user training.
=====
John Posada, Senior Technical Writer
mailto:jo...@tdandw.com, 732-259-2874
__________________________________________________
Do You Yahoo!?
Find a job, post your resume.
http://careers.yahoo.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author! iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,00 retailers. Join our almost
10,000 published authors today. http://www.iuniverse.com/media/techwr
Tom Murrell
|
| What message? That the software was easier to use and not subject to
| errors. As far as using the document to use the application...his
| response: "How should I know...I don't have a login and password for
| the application."
|
| Who is using MY document? Yup, technical support and user training.
Not to belittle the problem you raise, John, but after reading your post the
thought that came to mind was, "Know thy audience."
I see some logic in diving tech support and training more detail, real world
detail, on using the application than the sales force needs. Sales needs to
talk about all the neat things the software does and how it will help the
customer do what needs to be done faster/better/cheaper.
The working troops--particularly in tech support and training--need to know how
to make it work when it's being contrary. (I hate contrary software.) Now, one
could argue that once the sale is made, the users should have your document
over the sales document. And I can see an argument being made that the sales
folks need to know how to make the software look good when it's behaving
badly--error messages, hanging in loops, and other anti-social software
behavior--but that seems like an argument that lost.
So be glad somebody needs your document.
=====
Tom Murrell
Lead Technical Writer
Alliance Data Systems
Columbus, Ohio
mailto:tmur...@columbus.rr.com
Personal Web Page - http://home.columbus.rr.com/murrell/index.html
Page Last Updated 07/15/01
__________________________________________________
Do You Yahoo!?
Find a job, post your resume.
http://careers.yahoo.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author! iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,00 retailers. Join our almost
10,000 published authors today. http://www.iuniverse.com/media/techwr
Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.
John Posada
| real world
| detail, on using the application than the sales force needs. Sales
| needs to
| talk about all the neat things the software does and how it will
| help the customer do what needs to be done faster/better/cheaper.
My mistake...this isn't software that the sales force sells...it is
software that the sales force USES. It is a front-end to our Siebel
and SAP enterprise applications that they use to run their sales
process. If they run into a problem with the application (write
quotes, check credit status, allocate resources, etc.) and they
cannot get support immediately, then their sales process stalls
=====
John Posada, Senior Technical Writer
mailto:jo...@tdandw.com, 732-259-2874
__________________________________________________
Do You Yahoo!?
Find a job, post your resume.
http://careers.yahoo.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author! iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,00 retailers. Join our almost
10,000 published authors today. http://www.iuniverse.com/media/techwr
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ej...@raycomm.com) for details and availability.
---