Re: Must documentation always follow the UI?

[Keith Hood <bus -dot- write -at- gmail -dot- com>]

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