RE: Task-based versus UI-based documentation

Subject: RE: Task-based versus UI-based documentation
From: Lynne Wright <Lynne -dot- Wright -at- tiburoninc -dot- com>
To: "Lippincott, Richard" <RLippincott -at- as-e -dot- com>, Julie Stickler <jstickler -at- gmail -dot- com>, "Cardimon, Craig" <ccardimon -at- m-s-g -dot- com>
Date: Thu, 7 Aug 2014 16:49:42 +0000

In my experience with hardware vs software documentation, creating hardware documentation involves more one-on-one time with SMEs to learn how the thing works (with software I can figure out a lot on my own just by using the product); and a lot of time creating drawings (the engineers' design drawings and schematics tended to be far too complex than what the end user needed to know). And you need to be really careful to make sure that all the numbers and other details that you cite... from specs to serial numbers ... are correct and consistent. So in those regards, the skill-set focus for hardware manuals is different from software manuals.

But yeah, in terms of actual writing, the same principles apply.

-----Original Message-----
From: techwr-l-bounces+lynne -dot- wright=tiburoninc -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+lynne -dot- wright=tiburoninc -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Lippincott, Richard
Sent: August-07-14 11:16 AM
To: Julie Stickler; Cardimon, Craig
Cc: TechWR-L
Subject: RE: Task-based versus UI-based documentation

Julie Stickler said:
> Hardware documentation may be a whole different animal. I wouldn't know, I'm not a hardware writer.

Hardware writing is pretty much like writing about software, just that it hurts more when you drop the actual product on your foot.

We in this profession get very hung up on differences between software and hardware writing. I'm doing both now, have done both in the past, and my observation is that in the end, we're all just explaining things. There's more similarity between a hardware-based operator manual and a UI-based software manual than there is between the UI-based software manual and API/SDK documentation. Or, for that matter, than there is between a hardware-based system operator manual and system's schematic-based diagnostic manual or an illustrated parts breakdown.

Good practices of accuracy, clear writing, and logical organization apply to both hardware and software. (Of course they do, why would they not?)

Never been quite able to figure out why people get so hung up in the difference.



Rick Lippincott, Technical Writer
American Science and Engineering, Inc. | www.as-e.com Office +1-978-262-8807 | Fax +1-978-262-8702 rlippincott -at- as-e -dot- com
Follow us on Twitter @ase_detects









-----Original Message-----
From: techwr-l-bounces+rlippincott=as-e -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+rlippincott=as-e -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Julie Stickler
Sent: Thursday, August 07, 2014 10:54 AM
To: Cardimon, Craig
Cc: TechWR-L
Subject: Re: Task-based versus UI-based documentation

Writing UI based documentation assumes that your customers ALREADY KNOW where they need to go in your software to perform a task. Which is
completely ridiculous if your product has any sort of complexity. The
software products I am currently working on have tabs, subtabs, and then further subtabs. There are actions buried two or three levels deep, actions that you can do in dialog boxes, and really, no way that you could possibly know that there are additional settings for e-mail that are NOT on the E-mail tab.

Writing task based documentation is basically saying, "What are you trying to do? OK, here's how you do it." Which only makes sense.

Maybe if you're documenting something simple like a mobile app, you can write UI based documentation. I'm not saying it's not possible. But I think that in most cases, it's much less helpful than writing task based documentation. Your users are using software to DO something, they're performing tasks. Why wouldn't you write the documentation to help them perform those tasks?

Hardware documentation may be a whole different animal. I wouldn't know, I'm not a hardware writer.


On Thu, Aug 7, 2014 at 7:59 AM, Cardimon, Craig <ccardimon -at- m-s-g -dot- com> wrote:

> On another forum I frequent, many of the projects discussed are
> required to follow the UI. For example, each tab of the home page is a topic.
>
> I believe the members of this forum advocate task-based documentation,
> but I thought I'd ask:
>
> What method do the TechWhirlers prefer: Task-based or UI-based
> documentation?
>
> Personally, I do things in a UI-based manner because that is what my
> clients want.
>
>
>
> Cordially,
>
> Craig Cardimon | Technical Writer
> Marketing Systems Group
>
>
> Information contained in this e-mail transmission is privileged and
> confidential. If you are not the intended recipient of this email, do
> not read, distribute or reproduce this transmission (including any
> attachments). If you have received this e-mail in error, please
> immediately notify the sender by telephone or email reply.
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Read about how Georgia System Operation Corporation improved teamwork,
> communication, and efficiency using Doc-To-Help |
> http://bit.ly/1lRPd2l
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as jstickler -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
>



--
Julie Stickler
http://heratech.wordpress.com/
Blogging about Agile and technical writing

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l

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

You are currently subscribed to TECHWR-L as rlippincott -at- as-e -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


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l

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

You are currently subscribed to TECHWR-L as Lynne -dot- Wright -at- tiburoninc -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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l

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

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


References:
Task-based versus UI-based documentation: From: Cardimon, Craig
Re: Task-based versus UI-based documentation: From: Julie Stickler
RE: Task-based versus UI-based documentation: From: Lippincott, Richard

Previous by Author: RE: Software documentation that uses effective visual metaphors?
Next by Author: RE: Font tussle -- bolding bolding everywhere
Previous by Thread: Re: Task-based versus UI-based documentation
Next by Thread: RE: Task-based versus UI-based documentation


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


Sponsored Ads