Re: Task-based versus UI-based documentation

[John G <john -at- garisons -dot- com>]

I prefer Task-based, but it's more difficult to do.

I try to group related tasks together into a single topic/article, provide
an overview of the larger topic, and then a breakdown of the related tasks
in a way that shows how they all work together. This lets me provide
information in such a way that it does more than just explain how to do
something, it shows why it is that way and what happens to other things as
a result.

Generally, well-designed systems have UI pages that relate to a single
"thing" - either a task or a function of some sort. I can almost always
find a task that I've documented (or create something) that closely matches
the UI page and then link the UI page to the help article. Sometimes, only
one piece of an article is relevant to a UI page, so I provide links to
anchors in the help file so that the relevant piece appears at the top of
the page when they launch help.

IMHO, the users benefit when they see all the related bits together - even
if they're not looking for "B" they might see it when reading about "A" and
thereby teach themselves more about how things work.

TLDR: Put related ideas, functions, and procedures together so that it's
easier to explain how they work together, then direct people to relevant
sections as needed.

My 2Â,

JG


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 vwritert -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
>

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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