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.
Subject:RE: "A few things tech writers frequently say" From:Jen <jennee -at- gmail -dot- com> To:"techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Wed, 20 Nov 2013 10:35:50 +0200
I mostly agree with his his points.
1. Videos are too tedious to watch - I'd rather have the text that I can
go right to.
Big yes. I hate sitting through a video for 10 minutes when I could find
the information in 30 seconds in a text.
2. Users only go to help to search for a specific answer, so they want
a short topic rather than having to wade through a lot of content.
Not always. As a user, if I'm just learning to use a product, I might need
some conceptual information first, because I don't yet know *what* I'm
looking for. Maybe splitting the conceptual info in its own topic and
having small procedural topics is the best approach.
3. My preferred way to get help is to have a friend right beside me to
ask questions whenever I need it.
Depends on the friend :) If it's someone I'm actually friendly with, yeah,
I'll definitely ask, and go to online help only if the friend doesn't know
the answer. If the friend is a less-close coworker, I'll search help first,
because I don't want to pester him/her with silly questions. (For
statistics purposes: I'm somewhere between intro- and extroverted, leaning
towards introverted.)
4. If I do a search on Google, I'll find the content I'm looking for,
but not when I use the application's search.
I don't remember ever using the application's help if Google was an option.
(In my previous job, the application's online help was password-protected,
so I had to use it... )
5. Tech writers don't include more examples because they don't have
the information to write examples.
Yes and no. Sometimes the tech writer doesn't ask enough questions.
Sometimes the SME won't help no matter how many questions you ask. If
management doesn't care about documentation, you won't have any leverage.
Message: 2
> Date: Tue, 19 Nov 2013 12:02:15 -0800
> From: Tony Chung <tonyc -at- tonychung -dot- ca>
> To: "Cardimon, Craig" <ccardimon -at- m-s-g -dot- com>
> Cc: TECHWR-L <techwr-l -at- techwr-l -dot- com>
> Subject: Re: "A few things tech writers frequently say"
> Message-ID:
> <
> CAPnOPiFX7hbROL9wQ_Y93V4ZEaa69aCkE63QaCnOmb5J2WqQdQ -at- mail -dot- gmail -dot- com>
> Content-Type: text/plain; charset=windows-1252
>
> I disagree with everything Tom Johnson says. Just because.
>
> (Tom: You know I love you, right? ;-) )
>
> All kidding aside, my thoughts are:
>
> 1. Videos are too tedious to watch ? I?d rather have the text that I can go
> right to.
> - It depends. A video with a summary usually provides enough clues to let
> the user know whether the video is even worth watching. If there are
> detailed steps in the video, the written steps will aid as a reference
> guide so the user doesn't have to watch the whole thing again. This could
> also pertain to podcasts. Michael Hyatt posts full transcripts of all his
> podcasts. Some people really like to read rather than watch or listen. You
> can't exclude those people. For me, I often skip every video posted to
> social media because I just don't have time to focus on them, and you can't
> easily skim a video.
>
> 2. Users only go to help to search for a specific answer, so they want a
> short topic rather than having to wade through a lot of content.
> - It depends: Every page being page one is no excuse for writing long
> missives where only a portion could be what the user was actually looking
> for. It helps to define our content based on generic content types:
> concept, reference, task, etc. and then direct the user based on perceived
> need. However, we often don' t have access to the user's preferences so we
> have to play tour guide to ourselves to prove the idea works, then request
> feedback to tailor the experience.
>
> 3. My preferred way to get help is to have a friend right beside me to ask
> questions whenever I need it.
> - It depends: For many things this works out well. For introverts, they
> prefer to spend some time alone with their thoughts, and feel nervous with
> a friend. Virtual friend is kind of creepy.
>
> 4. If I do a search on Google, I?ll find the content I?m looking for, but
> not when I use the application?s search.
> - For the most part I use Google rather than try to search MSDN. Google
> Enterprise Search can be installed locally, and it works just fine for
> super-secret content behind a firewall.
>
> 5. Tech writers don?t include more examples because they don?t have the
> information to write examples.
> - The technical writer is not the SME. If the tech writer doesn't ask for
> specific examples to do something, the SME cannot provide them. Often the
> SMEs provide examples as sample code that cannot execute out of context.
> The writer will not necessarily know this, but the writer must ask. Tech
> writers vary from place to place. Many are former engineers. Others are
> closet poets. But the process should be the same: Ask, Write, Test, and Ask
> again. And again.
>
>
> -T
>
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
