Re: spec writing - is simple ever wrong ?

Subject: Re: spec writing - is simple ever wrong ?
From: Chris Morton <salt -dot- morton -at- gmail -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Tue, 30 Jul 2013 16:59:39 -0700

It could possibly be stated that you have an abundance of eruditeness; that
is to say that your articulation of the matter transcends all others.

> Chris

On Tue, Jul 30, 2013 at 4:32 PM, Diana Corrigan <
Diana -dot- Corrigan -at- visionsoftware -dot- com> wrote:

> I have had similar problems over the years with fake legalese. When pushed
> to explain their case, people who put it in docs often think it sounds more
> 'professional'. It doesn't. They have not thought their logic through.
> Hopefully they see this when I say, we *are* professionals and we show we
> are professionals when we say exactly what we mean (as systems
> professionals) in language most easily understood by our readers, and leave
> the legal words for lawyers.
>
> Cheers, Diana
>
>
> -----Original Message-----
> From: techwr-l-bounces+diana.corrigan=
> visionsoftware -dot- com -at- lists -dot- techwr-l -dot- com [mailto:
> techwr-l-bounces+diana -dot- corrigan=visionsoftware -dot- com -at- lists -dot- techwr-l -dot- com] On
> Behalf Of Chris Morton
> Sent: Wednesday, 31 July 2013 11:13 a.m.
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: spec writing - is simple ever wrong ?
>
> I think we flushed this all out many months ago when I objected to the use
> of "shall" in these docs, e.g., "The frabulator shall frabulate."
>
> It appears that much of what we wrangle is a holdover of gubmint spec
> work, with an abundance of parties apparently being insistent on promoting
> such stilted language in perpetuity.
>
> > Chris
>
> On Tue, Jul 30, 2013 at 3:39 PM, Monique Semp <monique -dot- semp -at- earthlink -dot- net
> >wrote:
>
> > Hello, WR-L-ers,
> >
> > I'm editing a specification, and I was merrily redlining all sorts of
> > convoluted wording to be simple and straight-forward. But then I
> > thought, perhaps there's a reason that so many specs are so awkward to
> > read. Maybe there is some spec writing requirement, beyond the usual
> > SHOULD, MUST NOT, etc. definitions, that in effect requires
> > indirectness? After all, why else would so many specs be so difficult to
> make out?
> >
> > For example, why should a spec say "in the case of" instead of "if"?
> > Why should "moreover" be used so much more often than "and",
> > especially when both could be omitted altogether?
> >
> > Any thoughts?
> >
> > For reference:
> >
> > * I did find the RFC Document Style Manual,
> > http://web.archive.org/web/20090418061257/http://www.rfc-editor.org/rf
> > c-style-guide/rfc-style-manual-08.txt,
> > but it certainly doesn't say to be excessively wordy!
> >
> > * Not really related, but interesting, is this thread about
> > programming language specifications:
> >
> http://programmers.stackexchange.com/questions/23542/how-do-i-go-about-writing-a-programming-language-specification
> .
> > I haven't digested it fully yet, but it doesn't seem to be concerned
> > with natural (vs. programming) language issues.
> >
> > -Monique
> >
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > New! Doc-to-Help 2013 features the industry's first HTML5 editor for
> > authoring.
> >
> > Learn more: http://bit.ly/ZeOZeQ
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as salt -dot- morton -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
> >
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> New! Doc-to-Help 2013 features the industry's first HTML5 editor for
> authoring.
>
> Learn more: http://bit.ly/ZeOZeQ
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as
> Diana -dot- Corrigan -at- visionsoftware -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
>


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more: http://bit.ly/ZeOZeQ

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

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:
spec writing - is simple ever wrong ?: From: Monique Semp
Re: spec writing - is simple ever wrong ?: From: Chris Morton
RE: spec writing - is simple ever wrong ?: From: Diana Corrigan

Previous by Author: Re: spec writing - is simple ever wrong ?
Next by Author: OT: Wise sayings (was spec writing)
Previous by Thread: RE: spec writing - is simple ever wrong ?
Next by Thread: Re: spec writing - is simple ever wrong ?


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


Sponsored Ads