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

Subject: Re: TECHWR-L Digest, Vol 119, Issue 13
From: vijayalaxmi jigajini <viji -dot- jigajini007 -at- gmail -dot- com>
To: Craig <ccardimon -at- m-s-g -dot- com>
Date: Thu, 24 Sep 2015 13:38:07 +0530

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


Previous by Author: Re: Optimal line length for sales documents in pdf
Next by Author: RE: Metrics used to evaluate Technical Writing/Publications
Previous by Thread: Re: Must documentation always follow the UI?
Next by Thread: Optimal line length for sales documents in pdf


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

Sponsored Ads


Sponsored Ads