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