Re: Must documentation always follow the UI?

[Reid Gray <reach -dot- reid -at- gmail -dot- com>]

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