Re: Must documentation always follow the UI?

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

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