Re: Describing field meanings and instructions

Subject: Re: Describing field meanings and instructions
From: kafkascampi <kafkascampi -at- gmail -dot- com>
To: "Cardimon, Craig" <ccardimon -at- m-s-g -dot- com>
Date: Thu, 22 Oct 2015 11:49:05 -0700

Lesli asked about documenting fields in software UI.
---

To take the DITA approach, you would have a Reference topic that
documents each field, and you would link it as a Related Topic at the
end of each Task topic (using a reltable).

The philopsophy here is not to break up the flow of the task, but
allow the user to reference the table if they need to.

HTH

Chris

On Thu, Oct 22, 2015 at 7:58 AM, Cardimon, Craig <ccardimon -at- m-s-g -dot- com> wrote:
> Excellent question. I will be following the responses.
>
> ~Craig
>
> -----Original Message-----
> From: techwr-l-bounces+ccardimon=m-s-g -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+ccardimon=m-s-g -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Lesli Ritchie
> Sent: Thursday, October 22, 2015 9:36 AM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Describing field meanings and instructions
>
> I always struggle with this one. Our software User Guides describe all the fields on a screen and give the user step-by-step instructions on how to do something, such as add a new record. I usually add a table that describes the fields and their options in the context of the steps, but I feel that this breaks the flow and could be confusing to a new user (our users have a wide skill range). How do you handle this? Do you reference a table of field descriptions within the instructions and then add it to an Appendix? Do you keep it in the instructions? I'd be grateful for ideas.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as ccardimon -at- m-s-g -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
> 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.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as kafkascampi -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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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


References:
Describing field meanings and instructions: From: Lesli Ritchie
RE: Describing field meanings and instructions: From: Cardimon, Craig

Previous by Author: Re: what's the current trend?
Next by Author: writing for translation
Previous by Thread: Re: Describing field meanings and instructions
Next by Thread: RE: Describing field meanings and instructions


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


Sponsored Ads