Re: TECHWR-L Digest, Vol 119, Issue 13

[vijayalaxmi jigajini <viji -dot- jigajini007 -at- gmail -dot- com>]

Good question Craig.

If a screen has many elements and you are describing the layout of such a
screen, then it is fine to go with the UI/Interface. Also, it is alright to
describe the UI if the modules are not interdependent or stand-alone.

If the modules are interlinked, then I would suggest the document follows
the workflow-based approach.

Thanks,
Vijji

On Thu, Sep 24, 2015 at 11:25 AM, <techwr-l-request -at- lists -dot- techwr-l -dot- com>
wrote:

> Send TECHWR-L mailing list submissions to
>         techwr-l -at- lists -dot- techwr-l -dot- com
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         http://lists.techwr-l.com/mailman/listinfo/techwr-l
> or, via email, send a message with subject or body 'help' to
>         techwr-l-request -at- lists -dot- techwr-l -dot- com
>
> You can reach the person managing the list at
>         techwr-l-owner -at- lists -dot- techwr-l -dot- com
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of TECHWR-L digest..."
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Learn more about Adobe Technical Communication Suite (2015 Release) |
> http://bit.ly/1FR7zNW
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
>
>
>
> Today's Topics:
>
>    1. Must documentation always follow the UI? (Cardimon, Craig)
>    2. Re: Must documentation always follow the UI? (John G)
>    3. Re: Must documentation always follow the UI? (Robert Lauriston)
>    4. Re: Must documentation always follow the UI? (Mike Starr)
>    5. Re: Must documentation always follow the UI? (Gene Kim-Eng)
>    6. Re: Must documentation always follow the UI? (Mike Starr)
>    7. Re: Must documentation always follow the UI? (Robert Lauriston)
>    8. Re: Must documentation always follow the UI? (Suzette Leeming)
>    9. Re: Must documentation always follow the UI? (Keith Hood)
>   10. Re: Must documentation always follow the UI? (John G)
>   11. Re: Must documentation always follow the UI? (Reid Gray)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Wed, 23 Sep 2015 19:18:08 +0000
> From: "Cardimon, Craig" <ccardimon -at- M-S-G -dot- com>
> To: "'TechWhirl (techwr-l -at- lists -dot- techwr-l -dot- com)'"
>         <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Must documentation always follow the UI?
> Message-ID:
>         <7AAC13DC756EEA4CB5360BDB593E4B89541A5D4D -at- Delmar3 -dot- m-s-g -dot- com>
> Content-Type: text/plain; charset="us-ascii"
>
> 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.
>
>
> ------------------------------
>
> Message: 2
> Date: Wed, 23 Sep 2015 15:26:43 -0400
> From: John G <john -at- garisons -dot- com>
> To: "Cardimon, Craig" <ccardimon -at- m-s-g -dot- com>
> Cc: "TechWhirl \(techwr-l -at- lists -dot- techwr-l -dot- com\)"
>         <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Re: Must documentation always follow the UI?
> Message-ID:
>         <
> CAFJnaP5B769W1Cnss6RmDPNxkA3HktNL4jQcpaSRaNrkATM2NQ -at- mail -dot- gmail -dot- com>
> Content-Type: text/plain; charset=UTF-8
>
> 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
> >
>
>
> ------------------------------
>
> Message: 3
> Date: Wed, 23 Sep 2015 12:29:22 -0700
> From: Robert Lauriston <robert -at- lauriston -dot- com>
> To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Re: Must documentation always follow the UI?
> Message-ID:
>         <
> CAN3Yy4Co7fm-wTC1wt-ZkETp1wh356fZFKEknRXP9Rmjm2+z0g -at- mail -dot- gmail -dot- com>
> Content-Type: text/plain; charset=UTF-8
>
> In that specific situation, I'd say it might be easier to copy the
> order on the screen, since there are so few items.
>
> Around 8-10  items it starts to get easier to alphabetize instead.
>
>
> On Wed, Sep 23, 2015 at 12: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
>
>
> ------------------------------
>
> Message: 4
> Date: Wed, 23 Sep 2015 14:30:02 -0500
> From: Mike Starr <mike -at- writestarr -dot- com>
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: Must documentation always follow the UI?
> Message-ID: <3354825e49696d2f8762febf4983fbe2 -at- writestarr -dot- com>
> Content-Type: text/plain; charset=US-ASCII; format=flowed
>
> I would use the same sequence as the UI but I would also find out from
> the development team why they sequenced the UI the way they did.
> Sometimes there's a good (but not readily apparent) reason for an
> unusual sequence.
>
> I once worked on a software product that had a drop-down lost box with
> about 50 elements in random order. I badgered the lead programmer until
> it got re-sequenced into alphabetic order... easier for the user and
> easier for the technical writer.
>
> Best Regards,
>
> Mike
> --
> Mike Starr                             WriteStarr Information Services
> Technical Writer   -    Online Help Developer   -   WordPress Websites
> Graphic Designer - Desktop Publisher - Custom Microsoft Word templates
> (262) 694-1028   -  mike -at- writestarr -dot- com   -  http://www.writestarr.com
> President - Working Writers of Wisconsin http://www.workingwriters.org/
>
> On 2015-09-23 2:18 pm, Cardimon, Craig 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
>
>
> ------------------------------
>
> Message: 5
> Date: Wed, 23 Sep 2015 12:30:10 -0700
> From: Gene Kim-Eng <techwr -at- genek -dot- com>
> To: "Cardimon, Craig" <ccardimon -at- M-S-G -dot- com>,    "'TechWhirl
>         (techwr-l -at- lists -dot- techwr-l -dot- com)'" <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Re: Must documentation always follow the UI?
> Message-ID: <5602FDC2 -dot- 2030104 -at- genek -dot- com>
> Content-Type: text/plain; charset=windows-1252; format=flowed
>
> Have you talked to anyone to find out whether there is a functional
> reason for the current layout, even if it doesn't seem as if there is?
> If not, then the first priority should really be to get the functions
> reordered on the landing page. And if that doesn't go anywhere, I'd
> describe it the way it is.
>
> Documenting a poorly designed UI doesn't make it any less so, but
> documenting it the way it probably should be rather than the way it
> really is will just call more attention to the low quality of its design.
>
> Gene Kim-Eng
>
>
>
> On 9/23/2015 12:18 PM, Cardimon, Craig 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 techwr -at- genek -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
> >
> >
>
>
>
> ------------------------------
>
> Message: 6
> Date: Wed, 23 Sep 2015 14:34:50 -0500
> From: Mike Starr <mike -at- writestarr -dot- com>
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: Must documentation always follow the UI?
> Message-ID: <871fe30b0a87f5bec30cd5a606e1acce -at- writestarr -dot- com>
> Content-Type: text/plain; charset=UTF-8; format=flowed
>
> It's not always all about task-based documentation. There is a time and
> place for reference documentation. At some point, users need to be able
> to understand every UI element even when we don't provide them with
> documentation for a task that uses that particular element.
>
> Best Regards,
>
> Mike
> --
> Mike Starr                             WriteStarr Information Services
> Technical Writer   -    Online Help Developer   -   WordPress Websites
> Graphic Designer - Desktop Publisher - Custom Microsoft Word templates
> (262) 694-1028   -  mike -at- writestarr -dot- com   -  http://www.writestarr.com
> President - Working Writers of Wisconsin http://www.workingwriters.org/
>
> On 2015-09-23 2:26 pm, John G 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
>
>
> ------------------------------
>
> Message: 7
> Date: Wed, 23 Sep 2015 12:43:42 -0700
> From: Robert Lauriston <robert -at- lauriston -dot- com>
> To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Re: Must documentation always follow the UI?
> Message-ID:
>         <
> CAN3Yy4ATHmy7ewJL6Y0x15QabOJKpJJhiHROa_wo5ShBbXy7kQ -at- mail -dot- gmail -dot- com>
> Content-Type: text/plain; charset=UTF-8
>
> If this *were* task-based, and the task was filling out a form for an
> initial configuration, then I'd use the "tab" order of the fields.
>
> Documenting self-explanatory UI elements such as "path" or "file name"
> is clutter unless there's some value to add to what the user sees in
> the UI. E.g. "file name: the name of the file" is clutter, but "file
> name: 128 characters max." might be useful.
>
> On Wed, Sep 23, 2015 at 12:34 PM, Mike Starr <mike -at- writestarr -dot- com> wrote:
> > It's not always all about task-based documentation. There is a time and
> > place for reference documentation. At some point, users need to be able
> to
> > understand every UI element even when we don't provide them with
> > documentation for a task that uses that particular element.
>
>
> ------------------------------
>
> Message: 8
> Date: Wed, 23 Sep 2015 16:37:00 -0400
> From: Suzette Leeming <suzette -dot- leeming -at- gmail -dot- com>
> To: Robert Lauriston <robert -at- lauriston -dot- com>
> Cc: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Re: Must documentation always follow the UI?
> Message-ID:
>         <
> CAFkQq3Mfxpa-zBdhu5A26ROBGrjn07rbKWaCC2mos5J5C_fm2g -at- mail -dot- gmail -dot- com>
> Content-Type: text/plain; charset=UTF-8
>
> What type of documentation are you creating? Is it user documentation?
> Reference documentation? Online help files? That will make a difference
> IMO.
>
> Suzette Leeming
>
>
> On Wed, Sep 23, 2015 at 3:43 PM, Robert Lauriston <robert -at- lauriston -dot- com>
> wrote:
>
> > If this *were* task-based, and the task was filling out a form for an
> > initial configuration, then I'd use the "tab" order of the fields.
> >
> > Documenting self-explanatory UI elements such as "path" or "file name"
> > is clutter unless there's some value to add to what the user sees in
> > the UI. E.g. "file name: the name of the file" is clutter, but "file
> > name: 128 characters max." might be useful.
> >
> > On Wed, Sep 23, 2015 at 12:34 PM, Mike Starr <mike -at- writestarr -dot- com>
> wrote:
> > > It's not always all about task-based documentation. There is a time and
> > > place for reference documentation. At some point, users need to be able
> > to
> > > understand every UI element even when we don't provide them with
> > > documentation for a task that uses that particular element.
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Learn more about Adobe Technical Communication Suite (2015 Release) |
> > http://bit.ly/1FR7zNW
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as suzette -dot- leeming -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
> >
>
>
> ------------------------------
>
> Message: 9
> Date: Wed, 23 Sep 2015 16:19:58 -0500
> From: Keith Hood <bus -dot- write -at- gmail -dot- com>
> To: John G <john -at- garisons -dot- com>
> Cc: "TechWhirl \(techwr-l -at- lists -dot- techwr-l -dot- com\)"
>         <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Re: Must documentation always follow the UI?
> Message-ID:
>         <
> CAG08JE0tG2SAWTzwSHRM2GfuCzyyF3fsO583HT2BkN36Y55rnA -at- mail -dot- gmail -dot- com>
> Content-Type: text/plain; charset=UTF-8
>
> 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
> >
>
>
> ------------------------------
>
> Message: 10
> Date: Wed, 23 Sep 2015 17:38:43 -0400
> From: John G <john -at- garisons -dot- com>
> To: Keith Hood <bus -dot- write -at- gmail -dot- com>
> Cc: "TechWhirl \(techwr-l -at- lists -dot- techwr-l -dot- com\)"
>         <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Re: Must documentation always follow the UI?
> Message-ID:
>         <CAFJnaP5Ojrj=
> AjdZdBWx59-XxAbnw-14JcC2yph3D1Nx_uwEPQ -at- mail -dot- gmail -dot- com>
> Content-Type: text/plain; charset=UTF-8
>
> 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
> >
>
>
> ------------------------------
>
> Message: 11
> Date: Wed, 23 Sep 2015 17:08:34 -0400
> From: Reid Gray <reach -dot- reid -at- gmail -dot- com>
> To: "Cardimon, Craig" <ccardimon -at- m-s-g -dot- com>
> Cc: "TechWhirl \(techwr-l -at- lists -dot- techwr-l -dot- com\)"
>         <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Re: Must documentation always follow the UI?
> Message-ID:
>         <
> CANVHTWxefYW2PjYiyhqZfH_SRbkgxoeoxD0UCYheAEmEOiFcbQ -at- mail -dot- gmail -dot- com>
> Content-Type: text/plain; charset=UTF-8
>
> Craig,
>
> Good observation. Very interesting question...   Documentation should fill
> in the information requirements or gaps and needs of the user for any
> particular use case or user scenario.  In that case, the doc certainly may
> stray from the UI.
>
> So, in what you aptly describe as "functions" of a UI ("affordances" in IA
> lingo) I would understand these as representing potential actions or
> outcomes --things which nearly always imply sequencing. (For example,
> "clean Data, sample data, train model, test model" and so on would look
> funny in a different order even if the user wants only to sample raw data
> and stop.)
>
> There are a few ways to approach this:
>
> - Group by relationship.
>   If there is an inherent process or sequence (dependencies between
> functions), bringing 'said' sequence to light is golden and ignoring means
> you risk losing the reader's attention/trust.
>
> - Common actions/ frequently used functions should not be hard to find.
> For example, the first and last items on a list stand out more than those
> in the middle.
>
> - Keeping things flat.
>   If you only expect to have < 7 or so functions, keeping them flat (in one
> view or page) and easily scanned is not such a bad deal. Organizing such a
> list as you propose is not a bad idea either.
>
> If you are writing an overview that describes the UI in excruciating
> detail, you should follow the structure of the UI.  I agree, alphabetical
> order is predictable, which means it is more inviting or pleasing, but your
> question reaches even further than that. It might also be an easy and
> obvious organizational device to get picked apart in a "bike shedding"
> moment of a review meeting.  Stick to the scenarios, they will help you
> decide what is best. Based on your user scenarios you should be able to
> reason if the functions are truly all 'stand-alone' or if their presence
> implies any such natural sequence or hierarchy.
>
> Best regards,
>
> Reid
>
>
>
> 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 reach -dot- reid -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
> >
>
>
> ------------------------------
>
> _______________________________________________
> You are currently subscribed to
> TECHWR-L.
> To unsubscribe send a blank email to
> http://lists.techwr-l.com/mailman/listinfo/techwr-l
> Send administrative questions to admin -at- techwr-l -dot- com -dot- 
>
> Visit
> http://www.techwhirl.com/ for more resources and info.
>
> Looking for the archived Techwr-l email discussions?  Search our public
> email archives @ http://techwr-l.com/archives
>
> End of TECHWR-L Digest, Vol 119, Issue 13
> *****************************************
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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