Re: Must documentation always follow the UI?

Subject: Re: Must documentation always follow the UI?
From: John G <john -at- garisons -dot- com>
To: Keith Hood <bus -dot- write -at- gmail -dot- com>
Date: Wed, 23 Sep 2015 17:38:43 -0400

I agree with you about using the same terms and spelling as what is on the
screen. I try hard not to describe or list items on the page as that only
leads to a maintenance nightmare when the developers get around to
alphabetizing lists, etc.

I will tell users how to use the page, though - what to click, what to do,
etc. - and as often as possible that is in the context of a task or
workflow.

JG


On Wed, Sep 23, 2015 at 5:19 PM, Keith Hood <bus -dot- write -at- gmail -dot- com> wrote:

> NEVER depart from the way it's done on the UI, no matter how logical your
> reasons. There WILL be someone who is dim enough that having different
> spelling or different order will throw him for a loop, and there WILL be
> some who will give your company grief because you make them spend an extra
> two seconds and preheat an extra three brain cells in order to correlate
> your work with the UI.
>
> On Wed, Sep 23, 2015 at 2:26 PM, John G <john -at- garisons -dot- com> wrote:
>
> > I try not to build a monument to the UI if I can possibly avoid it. The
> UI
> > exists in the code - why does it have to be reiterated in the
> > documentation?
> >
> > If you're writing task based content, just tell them how to use the UI -
> > Click "Abercrombie" to order high-markup clothes for preppies - but you
> > don't have to recount how and in what order things are organized on the
> > page - they can see that.
> >
> > And if you are presenting the contents of the page, for example, as links
> > to more information, I'd take a stab at listing the ones most likely to
> be
> > used first, and the ones least likely to be used last.
> >
> > tldr; Don't describe the page in words, and consider what the user is
> doing
> > with the page and cater to their needs.
> >
> > My 2Â,
> >
> > JG
> >
> >
> >
> > On Wed, Sep 23, 2015 at 3:18 PM, Cardimon, Craig <ccardimon -at- m-s-g -dot- com>
> > wrote:
> >
> > > Hello, Whirlers,
> > >
> > > How important is it that documentation exactly follow the interface?
> > >
> > > Hypothetical question: On the landing page of an application, functions
> > > are laid out in non-alphabetical order. There doesn't *seem* to be a
> > > functional reason for laying it out the way it is. Maybe they were
> > > developed in this order. Let's say it looks a bit random. Something
> like
> > > this:
> > >
> > >
> > > * Crotons
> > >
> > > * Abercrombie
> > >
> > > * Donuts
> > >
> > > * Fish
> > >
> > > * Ectoplasm
> > >
> > > * Birds
> > >
> > > * Guppies
> > >
> > > I was thinking that if I were writing the documentation, that I might
> lay
> > > out the docs in alphabetical order, to be more pleasing to the eye.
> > > Something like this:
> > >
> > >
> > > * Abercrombie
> > >
> > > * Birds
> > >
> > > * Crotons
> > >
> > > * Donuts
> > >
> > > * Ectoplasm
> > >
> > > * Fish
> > >
> > > * Guppies
> > >
> > > What would you all handle this situation?
> > >
> > > Cordially,
> > > Craig Cardimon | Senior Technical Writer
> > >
> > >
> > > 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.
> > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > Learn more about Adobe Technical Communication Suite (2015 Release) |
> > > http://bit.ly/1FR7zNW
> > >
> > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > >
> > > 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
> > >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Learn more about Adobe Technical Communication Suite (2015 Release) |
> > http://bit.ly/1FR7zNW
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as bus -dot- write -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
> >
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Learn more about Adobe Technical Communication Suite (2015 Release) |
> http://bit.ly/1FR7zNW
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> 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
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Learn more about Adobe Technical Communication Suite (2015 Release) | http://bit.ly/1FR7zNW

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

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:
Must documentation always follow the UI?: From: Cardimon, Craig
Re: Must documentation always follow the UI?: From: John G
Re: Must documentation always follow the UI?: From: Keith Hood

Previous by Author: Re: Must documentation always follow the UI?
Next by Author: Thanks to everyone!
Previous by Thread: Re: Must documentation always follow the UI?
Next by Thread: Re: Must documentation always follow the UI?


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


Sponsored Ads