Re: The GUI shall do...

Subject: Re: The GUI shall do...
From: Steven Jong <stevefjong -at- comcast -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Wed, 23 Jan 2013 16:31:22 +0000 (UTC)



I see "shall" a lot inÂrequirements documents Âwhere I work.ÂRequirements are often carefully negotiated in advance with a customer, and represent a contractual obligation. Since aÂrequirement s document Âdescribes future behavior and is binding, "shall" i s entirely appropriate.



Once theÂrequirements are Âtranslated into specifications, the language ought to change to describe whatÂ"will" happen. Future tense is appropriate, because the implementor is describing work that will be done and the way the product will behave. SpecsÂare often loose on this point , but unless a customer is seeing them it's not a concern. We can understand them.



When we translate the spec into customer documentation, both the verb "shall" and the future tense become inappropriate. WeÂare not documenting what the product must do or will do in the future, but what it does now. One of the ways in which we add value as technical communicators is to make this grammatical transformation.



In fact, it is a flaw to see customer documentation either with "shall " or future tense. Le aving aside all the arguments aboutÂclarity and translation,Âthe use of "shall" Âsuggests that the writer simply copied and pasted specification language, or worse requirements language, directly into the technical document. That's not adding value!



(I have seen technical documents using not only "shall" and not only future tense, but even subjunctive voice: "It would be nice if ProductName did ..."! Moreover, I could see in the source files formatting characters from the email system, proving that a previous writer had just copied and pasted an email into a book and sent it out that way. For shame--!)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
See what's new in Doc-To-Help 2012 in a free webcast:

Read all about them: http://bit.ly/C1-webcast
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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: Setup vs Set up [was Log in vs. login]
Next by Author: RE: Books for Usability Studies
Previous by Thread: Enjoying the winter weather (was RE: The GUI shall do...)
Next by Thread: Need Space near Boston for Tech Comm programs and workshops


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

Sponsored Ads


Sponsored Ads