TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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