Re: ADMIN: Why the Listowner's Such a Jerk, Again

["Huber, Mike" <mrhuber -at- SOFTWARE -dot- ROCKWELL -dot- COM>]

I think I said something similar last week in a thread about degrees: The
problem is BAD DOCUMENTATION. Not lack of degrees, not the lack of
standards, not the occasional typo, not that someone wrote "work-around"
when it should have been "workaround", not that Word is a pile of garbage
that would have been laughed off the market if any other company had tried
to release it, not that HTML isn't pretty enough for our fine art (hey, wait
a minute - I do use HTML for actual fine art - see www.sito.org).

BAD DOCUMENTATION is where the reader can't get the information he or she
needs, because it isn't there, or isn't expressed clearly, or because the
document isn't organized.

We need to focus more, here and in other places where people who write
documentation gather, like the STC. If we want more respect, or more money,
we have to write more good documentation and less bad documentation.

We need to get past being self-important professionals, past our delight at
making a living by writing, past our fine methodologies and spiffy
templates, past being right or wrong about grammar, and just plain produce
good documentation. We do that by thinking about the poor bastard who has to
make the thing we are writing about work, who can't yell down the hall to
the engineer who designed it. All the other stuff may help, but when you
think about it, the reader is going to suffer much more if Anon fails to
resolve the question of balancing the politics of the junior engineer's
position and expertise than if the other writer chooses wrongly between "a
SQL" and "an SQL".

---
Office:
mike -dot- huber -at- software -dot- rockwell -dot- com
Home:
nax -at- execpc -dot- com

>Bryan Zako wrote:
...
>
> The manuals I use on a day-to-day basis (possibly written by the same
> >authors of the email I've been getting all morning), are in
> general poorly written. Content is all over the place, information is
> missing, etc...there seems to be a genuine lack of understanding by
professional
> IT tech writers on how to put together a manual (I include MicroSoft in
this
> as well as other large software corps-- I hope I am not one of these,
> but who can say).
>
> I thought that others would share my concerns over the
> alarming state of documentation in the industry. That everyone would be
> talking about it and trying to find solutions. I thought I would get ideas
from
> other IT writers in the industry, the ones who are putting these docs
> together and who know they could do better. What they did wrong, how they
would do
>  it better next
> time, etc...


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=