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:Language guide for writing specifications From:"Moshe Kruger (AllWrite)" <moshe -dot- kruger -at- gmail -dot- com> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Sun, 14 Oct 2012 12:23:34 +0200
Hello all,
I am training a group of authors in writing functional and technical
specifications.
Since these documents have commercial impact for the solution provider
and their customer, clear and unambiguous language is critical.
1) Vagueness
I feel they should avoid vague words such as "could", "should", "can"
as in "the system could provide ..." or "the application can calculate
the sum this way or that way".
2) Excessive Legalese
Should authors use "shall" to describe the functions of the future
solution, or is "will" just as good, if not preferable?
Are there members of the forum who can point me to resources that will
help me in compiling a language guide for such documents?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.
Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.
