IET logo
 
IET
Decrease font size
Increase font size
Topic Title: Technical Documents
Topic Summary: grammar questions
Created On: 04 April 2014 07:21 PM
Status: Post and Reply
Linear : Threading : Single : Branch
1 2 Next Last unread
Search Topic Search Topic
Topic Tools Topic Tools
View similar topics View similar topics
View topic in raw text format. Print this topic.
 04 April 2014 07:21 PM
User is offline View Users Profile Print this message



Zs

Posts: 2964
Joined: 20 July 2006

Hello,

Well, this has made my head spin. Do any of you write technical documents?

I sent one of my documents to a proof reader this week.

I'm please to say that the comments on clarity are great but they have flagged a few things for my attention. Most of the comments are about my use of capital letters. So, I thought to myself, that's easy, I'll just refer back to the documents I used for my research and check their usage.

Ha, they are all over the place as well. I think I might have picked up engineers' disease? Or is it Engineers' disease?

So, my first question is how do you use capital letters and here are some examples. If it begins with a . then it means that it is the beginning of a sentence.

. Three Phase and Neutral
. Three phase and neutral
three phase and neutral
Three Phase and Neutral

. Supply Authority
. Supply authority
Supply Authority
supply authority

and so on.

How often do you put a capital letter in front of a noun? I reckon that we only do that if it is a real name such as a Faraday cage and that it would not be a Faraday Cage or a faraday cage.

Then this one, which is not so engineery, but still important;

How many spaces do you leave after a full-stop? I leave two and the comment says that is old fashioned and that it should only be one. They have actually suggested that I learned to type on a manual typewriter and that I really ought to be catching up . Yes, I did learn to type on a manual typewriter.

Ding. Smack. (some of you will get that )


Thank you for your help, I bet some of you are experts at this.

Zs
 04 April 2014 07:48 PM
User is offline View Users Profile Print this message



Zuiko

Posts: 521
Joined: 14 September 2010

Easy rules so you never ever make a mistake

1.) You can capitalize titles

2.) Other than that, only ever use capital letters for the first word in a sentence and proper nouns.


So write:

. Three-phase and neutral
three-phase and neutral

note the hyphen because you have modified and compounded two nouns. In everyday forum writing, it gets rather anal to bother with such things, but in a pucker technical document, it makes all the difference to look professional.


. Supply authority
supply authority

Neither of these are proper nouns so do not need capital letters. If the words are the titled name of something, then they do need them, for then it becomes a proper noun.




Full stops. One space. Two spaces was for typewriters.



1) Notice -ize (above)

This is NOT American English as some wrongly think. It is correct British (Oxford) English.

http://www.oxforddictionaries....finition/english/-ize

The creeping use of -ise is considered a disgrace by pedants!!!!

If you are unsure if the word is spelt ize or ise, then check it in an Oxford dictionary (or the above website, the preferred spelling is first in the list.)

Edited: 04 April 2014 at 07:59 PM by Zuiko
 04 April 2014 08:32 PM
User is offline View Users Profile Print this message



phantom9

Posts: 690
Joined: 16 December 2002

Hi Zs. I am always impressed with your writing style. You somehow capture a conversational feel to it. Most endearing.

Personally, I find that people over-use capital letters. I was brought up on an English writing system which was very strict with capital letters. Always used to start a sentence, thereafter only used for proper nouns, such as days of the week, months of the year, peoples' names, names of counties, names of countries and the like. There is nothing special about the words phase or neutral so it is my take that it would be as follows:

Three-phase and neutral (note the use of the hyphen)
if its the supply authority then its Supply Authority else lower case

If a document, especially a technical one, is filled with capital letters everywhere it becomes irritating to read and you start to just notice capital letters and lose concentration on the information being conveyed.

I wish I could proof read some technical stuff I would have an absolute field day correcting all the grammar. BS7671 would be filled with my comments as it stands!!!!!!
 04 April 2014 08:56 PM
User is offline View Users Profile Print this message



geoffsd

Posts: 357
Joined: 15 June 2010

Neither of these is a proper noun...
 04 April 2014 09:54 PM
User is offline View Users Profile Print this message



Zs

Posts: 2964
Joined: 20 July 2006

Thank you Phantom, very much.

Unfortunately there are times when proper-well-good English is called for. I struggle with that more than most of you I expect and I think that comes from way back and a decision to communicate at all levels as I speak. Phantom obviously gets it so I'm glad about that.

That has been fine all these years for conversation with the odd Lord, the odd electrician, or the odd convict. All on the receiving end of the same Zs. A kind of take as you find.

But, as the career develops, the need for something other than write as you speak and things like the use of the word proper (which I love Geoffsd, and smiled) step in and, she says with another Oxford comma, that is why this report went to a proof reader. New beginnings and all that. Not everybody who reads our written word is going to know us personally. I wonder if it might be easy to look like a pratt if the reader hasn't met us.

But on the other hand some of these 'Scholarly Articles' that I have been using from the web are dire.

Since writing my OP I have had a brief exchange with the proof reader. She has suggested that any definitive terms use capitals.
Electromagnetic Interference. Selection and Erection. Insulation Resistance.

I think I might explode.

Zs
 04 April 2014 10:32 PM
User is offline View Users Profile Print this message


Avatar for stateit.
stateit

Posts: 2203
Joined: 15 April 2005

I'm with your proof reader on definitive terms, as are you I expect.

I'm generally with Zuiko on '-ize' as well, excepting 'recognise' which for some reason makes me want to pull my receding hair out when I see it spelt with '-ize'.

When I'm writing specifications for people who may lie on the more layperson side of matters (sorry about that), then my definitive terms may be cast over a broade field.

When writing to' those-in-the-know', then those definitive terms become more narrow in their focus.

So there y'go... Horses For Courses.

I know a couple of current proof readers and have known more who have done the job in the past (in various fields). You should hear how good their grammar is after an afternoon of special sherbets...

[edit] As an afterthought...

I'm carrying out some work on a local village hall.

This village has on it's committee retired people who have overseen projects as large as the Channel Tunnel and nuclear power station commissioning (yes, it's an affluent village).

I had one of my proposals returned with MS Office 'Track Changes' all over it where they'd corrected me and sent it to-and-fro between themselves...

Getting a simple job involves being sat down in front of the Grand inquisition... [/edit]

-------------------------
S George
http://www.sg-electrical.com

Edited: 04 April 2014 at 10:39 PM by stateit
 05 April 2014 01:13 AM
User is offline View Users Profile Print this message



intrinsic4225B

Posts: 1623
Joined: 30 September 2004

Zs,

Not sure if you already have a copy of this or not, but just in case . . .

http://www.theiet.org/students...ech-report-writing.cfm
 05 April 2014 01:46 AM
User is offline View Users Profile Print this message



crossy

Posts: 81
Joined: 14 February 2006

Over many years of using, writing and reviewing technical and contractual documents a couple of things come to mind:-

1. Be consistent in use of capitalization
2. If it's a defined term it can have capitals, otherwise not (so if Supply Authority is in your definitions it can have capitals)
3. Use only one language, I see documents in UK English, US English, Australian English and even Indian English, I get narked when I see UK spelling in one section and US spelling in another, decidedly unprofessional.

and learn how to use shall, should, may and must and what they mean when you see them in a contract or technical document.
 05 April 2014 08:27 AM
User is offline View Users Profile Print this message



Cremeegg

Posts: 536
Joined: 13 July 2007

A sign of age - wanting to get things right - good on you Zs - although I wouldn't have thought you old enough! You writing style is always a joy to read and easy on the brain so keep going.

The lack knowledge of the Latin derivations of some words always bugs me. The commonest two I find are
1) more than one alternative when you can only ever have one as alternative is derived from the Latin altere meaning the one the other
2) under the circumstances when the Latin circum meaning round or around dictates that you cannot be under but can only be in the circumstances with all the stances around you not above you.

My two years Latin at school was enough to greatly increase my understanding of our English language in so many ways. Sadly my grammar, use of split infinitives and possessive apostrophes are still not my strongest points.

Now off to fix a tripping RCD!
 05 April 2014 09:14 AM
User is offline View Users Profile Print this message



phantom9

Posts: 690
Joined: 16 December 2002

I used to write technical documents for the MoD. One of my best attributes was keeping verb tense absolutely consistent throughout. For example, we used to do option studies. These were reports based on pros and cons. They were a stage in the sequence of managing projects. As these were option based it was always would, could, should. When the option was finally chosen and a project brief was to be formulated it was then will, can, shall. Option studies were often written around several reports written about each option and sifting through these was tedious when ambiguity was evident and often verb tenses were swapped around all over the place. It is not easy to write technical documents that convey a precise unambiguous message and define exactly what is required. BS7671 falls foul of this in a big way. I could re-write it and make it so much easier to understand.

Anyway, good luck with your quest, Zs, it is a nice challenge to have.
 05 April 2014 10:05 AM
User is offline View Users Profile Print this message



Zs

Posts: 2964
Joined: 20 July 2006

Ize ir ise? Zuiko's got me thinking. Fortunately there are few so on this report not a big issue. But I checked in with myself and decided I'm in the 'ise' camp. Sorry Zuiko but I think it looks aggressive. After all, there isn't room for too many Zs.

The consistency comment is appropriate. Given that all these research documents on my desk use different formats. Time to choose a format and to stick to it for the future I think.

I've a funny story for you. In the brilliant link posted by intrinsic there's a mention of spelling and spell-check of technical words.

We had a big design brief ready to go out, from the desk job, which had been edited and formatted by he in charge of such things. He hit the auto correct button on the word earthing. The entire report referred to 'earthling' . Good job we saw it.

Then again, a response to one of our designs came back from the client. All the disciplines get a column on a page in which to write our comments and suggest action. Internal only I should add. Usually we write 'noted' or something like 'this will be addressed at the next stage'. Well, one of the comments was about a bulleted list. It rightly said you either use a capital at the beginning or you don't and the list was all mixed up. 'Noted' . Two pages later he had written a bulleted list and it was all mixed up. 'WTF see page 2' went in my column. My boss chuckled but squarely advised me 'Zs, they do that to us but we rise above it and we don't do it back'.

Thanks for those. This is turning out to be very interesting.

And as for the habit of two spaces...cor that's hard to overcome and I might have to admit defeat on that.

Eleven and three quarters Cremegg

Zs
 05 April 2014 10:12 AM
User is offline View Users Profile Print this message


Avatar for JZN.
JZN

Posts: 562
Joined: 16 November 2006

A lot depends on where it will be published. I used to write for a number of publications and was employed by one publisher for a couple of years. There is something called "house style". Different publishers use different styles, formats and rules. Some will choose to follow Collins and others, Oxford. Irritating at times, but you might just have to live with what the publisher's subs and proof readers go for.

Regards
John
 05 April 2014 10:53 AM
User is offline View Users Profile Print this message


Avatar for sparkingchip.
sparkingchip

Posts: 6172
Joined: 18 January 2003

I understand Stateit's situation with the village hall committee, some years ago I was a school governor and as well as a considerable number of teachers the vicar was also a governor, and he was a English lecturer at the university on a part time basis. Often I seemed to be the only one concentrating on the content of documents rather than the spelling and grammar.

Now as I type this Google is automatically checking my spelling and grammar for me, despite that I have been accused of the over use of the ' key on my keyboard, too many apostrophes on this forum! Oh! And the overuse of exclamation marks.

Several years ago I did a job for a Birmingham University English lecturer and I questioned her on the use of the English language regards the past tense of words such as Zs has used in in her original post, this resulted in reference to books that provide guidance on such matters, then she told me I'm old!

Zs has put " I learned to type on a manual typewriter" now I would write "I learnt to type on a manual typewriter" (actually it's in my loft) I would use learned only in a reference to "my learned friend" as JP did in the post about Uo being 230 volts last week. Apparently I use the traditional Queens English with learnt rather than learned and burnt rather than burned while the majority of people has become Americanised particularly the younger people, hence the comment about me being old.


Andy

I have just checked, I have Google spell check set to UK English.

Edited: 05 April 2014 at 11:05 AM by sparkingchip
 05 April 2014 11:31 AM
User is offline View Users Profile Print this message



lyledunn

Posts: 632
Joined: 13 August 2003

Who neds proof reeders ani way. I ve bin riting tecknical documints for yeers and not any one has complaned.

-------------------------
Regards,

Lyle Dunn
 05 April 2014 12:28 PM
User is offline View Users Profile Print this message


Avatar for sparkingchip.
sparkingchip

Posts: 6172
Joined: 18 January 2003

Generally whilst working I am in mucky work clothes consisting of scuffed boots, knee pad holster pocket trousers and polo shirt with my name and "Builder & Electrician" embroidered on it very much the image of the hands on worker or dirty old digger man as I heard one old lady describe a tradesman that she thought was getting above himself!

Comment has been made by a number of my customers that my paperwork and documentation presents a completely different image, I'm glad to say.

There is a balance with technical documents between good grammar and what makes sense, in BS 7671 the are some references that do not make grammatical sense, but do make sense technically, so at this point it becomes a "technical term" because for example two words are linked by a hyphen that isn't grammatically correct.

Andy
 05 April 2014 12:56 PM
User is offline View Users Profile Print this message



phantom9

Posts: 690
Joined: 16 December 2002

The biggest challenge when writing technical reports is making the subject matter understandable. There are few who achieve this. Grammatical error has crept in to so much everyday speak that it has become a secondary issue.

"I was sat on the bus" is wrong. It is "I was sitting on the bus". Whereas "I sat down" is correct. However, I was sitting inside the bus is more accurate. If you were sitting on the bus you would quite literally be sitting on the roof of it. This is where a lot of technical jargon is misinterpreted. Saying what you mean doesn't necessarily mean what you say.

"I got an invite" is very very commonly spoken but is wrong. It is "I got (or received is better) an invitation".

"I haven't got no...." or "I haven't got none" is a double negative. People refuse to use the word "any" in everyday speech, it is just not cool to say "any" , it is always "no". But when written in a sentence it is so obviously poor it is generally corrected to "I haven't any..."

Another common mistake in report writing is to use unnecessary phrases like "As you may be aware" or "It goes without saying". These phrases have no real meaning and no place in technical reports. "It has to be said" or "I am sure you must be aware". Big no.

On a slightly different note, but still related to English, the most irritating phenomenon ever to infiltrate the spoken word is rising intonation at the end of a sentence as though the speaker is questioning everything they are saying. It is most prevalent amongst teenagers but sadly has escalated to everyone. It is such an irritating way of speaking but it is clearly the preferred manner nowadays.

On top of all this, the pronunciation of the letter 'h' so widely misspoken as 'haitch' aagh! Why people have to emphasise the huh sound when saying aitch is one of the most baffling things to me. You hear it said when people are spelling a word, or when children say the alphabet and I have absolutely no idea why? Its as though you may not understand what the letter is if it is not emphasised as "haitch". Most bizarre.
 05 April 2014 01:29 PM
User is offline View Users Profile Print this message



phantom9

Posts: 690
Joined: 16 December 2002

I don't know whether I should...but here goes anyway. My pet hate in the Regs. "Potentially dangerous"

Potentially dangerous has no place in technical writing. Take the two words in context and separate them. Potentially; something that may happen, but then again, it may not. Dangerous; something that may cause harm or injury or death or damage to property.

Put these two words together and you have too many options:
1. something that may happen but is not dangerous at the moment
2. something that may not happen but is dangerous at the moment
3. something that may happen and is dangerous at the moment
4. something that is not usually dangerous but could be

So if you are presented with a phrase like potentially dangerous in a technical document, such as BS7671, it is unforgivable because the person reading it needs to know what it is that is dangerous, how dangerous, when the danger can arise, why it might arise but isn't yet, how it may be dangerous and in which context the danger would be evident. It is just a ridiculous phrase and should never ever be used where somebody is faced with making a decision. There is insufficient information in the phrase potenytially dangerous to know what to do. This is one of the reasons there are so many arguments about coding in EICRs. Everyone will see a different angle to what the danger is and what the potential harm is.

So, what should be used instead of potentially dangerous?

This is very easy if you consider how the framework of society is developing towards hazard identification and risk assessment. People can relate immediately to something which is high risk, medium risk, or low risk of causing harm and it fits in with laws requiring risk assessments to be made.

So, in this context, we can quite simply improve the coding on an EICR using a quantifiable and meaningful reference

C1. Immediate or high risk of death or serious injury.
C2. Medium risk of serious injury.
C3. Low risk of any event

The difference in using quantifiable requirements like this evens the chance of uniform action as to what needs to be done and how urgently. Wishy-washy phrases like potentially dangerous are daft. If you were in a court being cross examined by a clever lawyer who asked you what you meant if you used the phrase potentially dangerous he would quite rightly want to know more information.

The problem I have is that people seem to support poor use of English, as though it is some kind of affront. "It is obvious to me what potentially dangerous means" and no you are wrong Phantom we don't need to change it.

In closing, if anyone wants to take the writing of the Regulations seriously, but then accept terms like potentially dangerous within its content, they should never contemplate writing technical documents they would be no good at it.

Edited: 05 April 2014 at 06:44 PM by phantom9
 05 April 2014 03:14 PM
User is offline View Users Profile Print this message


Avatar for redtoblackblewtopieces.
redtoblackblewtopieces

Posts: 206
Joined: 10 January 2013

LOL so bad a spilt the glass of red I was drinking , C1 all pretty straight forward please expand on C2 &3, and how if you coded something you thought ( possible quite rightly from an electrical hazard ) as C3 resulted in a serious injury ?
Kevin

-------------------------
Safety through a Standard
Compliance by Approved Documents
 05 April 2014 06:59 PM
User is offline View Users Profile Print this message



phantom9

Posts: 690
Joined: 16 December 2002

Happy now r2? It is a trait on forums to pick fault with suggested wording instead of focusing on the bigger picture. I am not saying the words I used are a final suggestion nor am I trying to re-write the words on here it is just using examples to illustrate my meaning. Trust you to use it as a definitive point to laugh about. Currently, the guidance for recipients appended to the condition report is atrociously worded.

Item 7. C1 "Danger present" the safety of those using the installation is at risk. Immediate remedial work recommended.
Item 8. C2 "Potentially dangerous", the safety of those using the installation may be at risk. Urgent remedial action recommended.
C3 Improvement recommended.

Totally worthless and of no use to anyone. A C1 is no different to a C2 because neither give weight to the risk. C2 those using the installation may be at risk (how much risk and to what level of detriment). How can a C2 be divided from a C1 with useless wording like this?
And as for a C3 there really is no need for a C3. Nothing in a C3 ie everything else, is worthy of a code. A climate of only doing C1s by recipients of reports is evident of total lack of understanding due to poorly worded warnings. To leave a C2 is against the intention of the warning, it should still be done. A C2 is still urgent but nobody is given enough information as to why it is urgent what the consequences of not doing it are. Too many options left for an informed decision because there is no information on which to base the urgency of the C2. C1 do it there and then? Hardly, some people wait for 6 months. Its nonsense.

Its like treading toffee with you lot.
 07 April 2014 10:20 AM
User is offline View Users Profile Print this message


Avatar for OMS.
OMS

Posts: 19747
Joined: 23 March 2004

For me it is usually ise not ize

Single space between senetences

Line and half spacing for font

Capitilisation for defined terms ? - which should be in the definitions section - most certainly in my view. So;

The Contractor shall employ the Supply Authority to provide a new Low Voltage supply to the Facility.

If you use a term such as Low Voltage, consider abbtreviation after the first use - ir should appear the first time as"................of the Low Voltage (LV) supply..........." for the next , "the LV supply shall.............

Keep the tense consistent with the stage of the report

If there is a house style, then use it

Try to avoid will, must etc in direction to others - ie "the Contractor shall supply Operation and Maintenance (O&M) manuals as described in Section..................."

Keep in mind that sometimes, deliberate but minor errors are introduced into documents and errors differ in different versions of them - basically the human animal is lazy - and the tendancy is to copy and paste rather than rewrite manifests itself, if you see a copy of certain aspects (usually out of context) - it's a means to identification of source. I can still spot documention that I wrote some time back being reused or recycled in some strange environments. As an example, I recently came across specific wording relating to "Section 607 earthing requirements..........." in a contractors document - written in such a way as to make it obvious (to me) where it had originated from - aside from the obvious raised eybrow over currency of course.

Other than that, don't sweat the small stuff is my advice - start with the idea of "is what I want to say being communicated to the target audience and do they understand it" - if so, then generally it's job done - the rest is just pedantry, and serves to deflect from the issues at hand.

Well, one of the comments was about a bulleted list. It rightly said you either use a capital at the beginning or you don't and the list was all mixed up. 'Noted' . Two pages later he had written a bulleted list and it was all mixed up. 'WTF see page 2' went in my column. My boss chuckled but squarely advised me 'Zs, they do that to us but we rise above it and we don't do it back'.


Pick the battles you need to win, bend the knee to the mundane froth clients generate, is the moral of that story - .

Remember, every interaction with the client costs you time and money

Regards

OMS

-------------------------
Failure is always an option
IET » Wiring and the regulations » Technical Documents

1 2 Next Last unread
Topic Tools Topic Tools
Statistics

See Also:



FuseTalk Standard Edition v3.2 - © 1999-2014 FuseTalk Inc. All rights reserved.