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