Re: "Age-old" question

Subject: Re: "Age-old" question
From: Helen OBoyle <hoboyle -at- gmail -dot- com>
To: Monique Semp <monique -dot- semp -at- earthlink -dot- net>
Date: Wed, 14 Sep 2016 04:20:12 +1000

> But evidence/behavior shows clearly that immediate budget concerns tend
to trump âlong-termâ

This seems to be more and more the case when dealing with "dot com" type
companies. I am fortunate at the moment to not be in that situation.
Device/software companies in the healthcare industry and engineering-heavy
hardware companies with a strong safety culture seem to be two types of
orgs that haven't moved in that direction yet.

> docs are very much still a ânecessary evilâ and a checkbox to complete as
quickly/cheaply as possible. Iâve seen quite a few writersâ job listings
for that have phrases such as âbalance right with right awayâ

Hello, "agile"! At least one very prominent software company (for whom I
do not work) in my state values the rapid creation of docs (check!), over
the (slower) creation of docs that would really help maximise the use
customers get out of the company's product. This is sad because it's the
mindset that results in API docs with field descriptions like:
buffsz: Size of buffer to allocate.

... which some orgs deem sufficient. Note that this contains no
information about a suggested parameter value, whether there are any
defaults if a magic value like 0 or a negative number is supplied as a
value, or factors to consider when choosing a buffer size, like "should be
a multiple of the size of the data you expect returned" or "the maximum
buffer size is 65536." It's the kind of description that really
disappoints experienced devs who are also trying to generate their own
"check!" for task completion at client sites and just want to know a "safe"
and non-performance-killing value to put in the field.

I suppose it's the curse of knowledge. I'm often writing documentation for
developers, and I "know too much" about what a developer might want to know
about an API or an internal algorithm. A writer whose dev experience was
limited to lightweight java and javascript/HTML in uni might see nothing
wrong with "Size of buffer to allocate."

Kind regards,

Helen.

On Wed, Sep 14, 2016 at 12:00 AM, Monique Semp <monique -dot- semp -at- earthlink -dot- net>
wrote:

> >Answer: "It's even more expensive to have CRM problems because customers
> are upset due to bad documentation."
>
> One would think so. But evidence/behavior shows clearly that immediate
> budget concerns tend to trump âlong-termâ (say, two quarters from now)
> reality. I suppose there must be some companies who donât operate that way,
> and certainly safety-conscious industries simply cannot ignore the need for
> proper docs. But in the B2B software industry that is dominant in the San
> Francisco Bay Area, it seems that docs are very much still a ânecessary
> evilâ and a checkbox to complete as quickly/cheaply as possible. Iâve seen
> quite a few writersâ job listings for that have phrases such as âbalance
> right with right awayâ, which certainly tells us what a company thinks of
> the tech writerâs work.
> -Monique
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as hoboyle -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
Re: "Age-old" question: From: Jody Zolli
RE: "Age-old" question: From: Wright, Lynne
Re: "Age-old" question: From: Monique Semp
RE: "Age-old" question: From: Cardimon, Craig
Re: "Age-old" question: From: Keith Hood
Re: "Age-old" question: From: Monique Semp

Previous by Author: Re: "Age-old" question
Next by Author: Re: Online help access question
Previous by Thread: Re: "Age-old" question
Next by Thread: Re: "Age-old" question


What this post helpful? Share it with friends and colleagues:


Sponsored Ads