TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
> 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
