Writing style guidelines

By Andreas Grondoudis

2

Overview

• Zobel, J., Writing for computer science: the art of effective communication, Springer, 2000

• Chapters 2 and 3– Writing style general guidelines• Tone, examples, motivation, analogies, examples, etc.

– Writing style specifics• Titles and headings, paragraphing, repetition,

emphasis, qualifiers, padding, jargon, overuse of words, tense and more.

3

Writing styles general guidelines• There are many styles of writing

– Plain, poetic, scientific, and more• What is the style of writing?

– It is the manner of expression– It is not writing correct grammar– It is about how well the text relays to the readers

• Science writing– Must be prosaic, ok it is not poetic– Just because its science it does not have to be dull– Clear and good use of English is essential– A lively style of writing suggests interesting ideas– Sloppy, disorganised writing is distracting and the readers are biased

against it

4

1. Economy

• Text should be strained• Every sentence necessary• Don't just add text for padding the meaningful ideas.

Filter and present what is needed.• Revise frequently and critically– Remember you are not writing this for yourself but for

the readers• When work is reviewed read the comments and

realise what can be done to better present the work.

5

2. Tone

• Be objective and accurate, remember you are writing to inform not entertain

• However, don't make the tone machine-like and boring, keep it simple, direct. Here are some basic rules– Have one idea per sentence (or paragraph)– Have simple, logical organisation– Use small words, short sentences with simple structure– Avoid 'buzzwords' and excess– Be specific while leaving out unnecessary material– Only break one of the above rules if there is a good reason

6

2. Tone continued

• Common fault: over-qualifying– Explaining and supporting a claim so much that it

ruins the reader's experience• You can use the first person (<we> or <I>) to

make the reading more pleasant• Don't outer your artistic impulses when writing

a paper• Don't dress up the ideas as if to put on a 'sales'

window

7

3. Motivation• Structure the paper to give purpose to the reader• The introduction gives some indication of the organisation

but linking from previous to next is also a good approach• If you are going to include anything explain why it is

included (and therefore 'vital' for the reader to read) and how it fits in the 'big picture'

• You are more aware of the material than the reader, explain everything that is NOT common knowledge

• Decide what you want to teach the reader and plan the content of your paper.

8

4. The upper hand

• OK we know more about the subject– DO NOT over-do it

• Appearing to be the super-researcher and general Mr know-it-all is tiresome – And can work against you

• You must write as an equal to the dullest of readers and attempt to convey your ideas in the clearest way possible.

9

5. Obfuscation

• It is the art of making statements in an ambiguous way so that even so you are saying little it might appear that you are giving a lot.

• Not common deliberatly• Vague writing is common• It is better to be specific

10

6. Analogies

• From the Greek word Αναλογία, they can be used to better explain a concept

• They can however prove to be curious because something might seem similar to me but not to you.

• They can (sometimes) take you of context, because differences are more basic (than the similarities)

11

7. Straw men

• An indefensible hypothesis posed just for being demolished

• Claiming against something that everyone knows to be untrue– Says 'bad' things about the author

• Contrasting a new idea with a bad alternative– Gives the bad alternative some worth and make the new

idea more important than it is– Contrast must be between the new and the current

• Contrasting a new idea against an ancient one

12

8. Reference and citation• You must

– Relate to existing work, show how we built on it, demonstrate differences from other results

– Include a list of references in a standard format and citation inside the text• References

– Demonstrate the newness of the work – Demonstrate the knowledge of the subject by the author and– Provide point of references for background reading

• Rules of contact– Refer to original papers rather than secondary referrals– Order of preference: Book or journal article; conference article; technical report;

manuscript; thesis; personal communication (avoid)– Don't cite what is common knowledge; substantiate claims; statements of fact and

previous work commentary– Refer to your previous work but don't over do it– Whatever you write be exact and refer to facts

13

8. Reference and citation (continued)

• Rules of contact (continued)– Attribute results correctly (regardless if you have the

original reference or not)– Describe results from other papers fairly and accurately– Be careful of wording (says, suggests, thinks)– Be wary of similar and/or different notations and

terminologies– Don't state something as true just because you think it

is true– Citations and quotations see slides for referncing

14

9. Acknowledgements, Ethics

• Acknowledgments– Thank all that contributed (in any way) to the

scientific content of the publication– List either with contribution type or without

• Ethics– Don’t present opinions as facts– Don't plagiarize (even yourself)– Do not publish the same result more than ones and

don't submit them to more than one publish routes.

15

10. Authorship, Grammar and Beauty

• Authorship is sensitive– Substantial contribution to the paper's intellectual content– Should have contributed in conception; execution and

interpretation of results.– Order is important (first = most significant most of the

times)• Grammar, as long as clarity is maintained. – Some readers are annoyed by too many grammar errors

• Beauty, simplicity, clarity

16

Writing Style Specifics

Title and headings The opening paragraphs Variation

Paragraphing Sentence structure Repetition and parallelism

Direct statements Ambiguity Emphasis

Definitions Choice of words Qualifiers

Padding Misused words Spelling conventions

Jargon Foreign words Overuse of words

Redundancy and Wordiness

Tense Plurals

Abbreviations Acronyms Sexist language

17

1. Titles and headings• Concise and informative, not necessarily complete sentences• Specific, simple, to the point (content)

– Example• BAD: An investigation of the effectiveness of extensions to standard ranking techniques for large

text collections• GOOD: Extensions to ranking techniques for large text collections

• Not too short, not too long• Must be accurate (rather than 'catchy')• Section headings should reflect the logical structure of the article• Don't have too many subsections and sub-subsections

– 3 headings on a page is not good, it makes for very small text blocks• Numbering

– Essential in bigger documents. Suggestion stick to 3 levels (no more)– Can be skipped in small documents and articles; just ensure that the font, the size and

the placement distinguish the sections

18

2. Opening paragraphs

• They are important and need to attract attention• They must be very clear and to the point stating the

context of the following text• They don't need to be technical (leave that for later)• If existing knowledge is included it must be

distinguished from the paper's contribution• Abstract– Has to be very good and provide the reader with a brief

account of the paper; put the work in context and clearly state the paper's contribution

19

3. Paragraphing• A paragraph should have a single, specific topic, ideally at the beginning

with the remainder of the body amplifying• Long sentences must be broken down

– They mean that the author has not clearly separated everything in their mind– They make readers boring and they get lost

• Neighbouring paragraphs should clearly link and make specific referrals• You could have listed paragraphs. They: 1)highlight points clearly;

2)context is obvious; 3)points considered separately without confusion and 4)points are easy to refer to.

• They can be numbered, named or tagged (bullet point or hyphen)• One disadvantage is that they highlight too much

– If you have something trivial, list it in a paragraph (like the 4th bullet point above)

20

4. Sentence structure

• Should have a simple structure• Be clear, brief and to the point.• Avoid nesting sentences• Long sentences are easy to create– Stating a principle, qualifying it, then explaining the

circumstances in which is holds and probably linking to the next subject

• Double negatives are difficult to parse from a reader– It is not a good practice not to comment your code

21

5. Repetition and parallelism

• Repeating words or phrases can become monotonous for the reader

• Avoid starting sentences with the same words• Concepts that relate are better to be

explained in parallel• Parallels can be based on antonyms• Standard form parallels– On one hand? First? One approach is?

22

6. Direct statements

• Don't use passive voice– BAD: the following theorem can now be proven– GOOD: we can now prove the following theorem

• Direct voice (active) is easier to read– I think, also easier to write

• Using 'we' will clearly distinguish the contribution of the paper

23

7. Ambiguity and Emphasis• Ambiguity

– Check for it carefully.– Familiarity with the material leads to pitfalls– When you use 'it', 'this' and 'they' make sure it is clear what they

refer to– Watch out for speed-time pairs (increase one you decrease the

other)• Emphasis

– The structure of a sentence 'focusing' on a word can change by rearranging the words.

– You can give emphasis with italics (but don't over do it)– The use of capitals is a no-no (at least for emphasis)

24

8. Definitions and choice of words• Definitions

– When something appears for the first time explain it (define it)– Use emphasis to make the user notice the definition

• Choice of words– Trend for short, direct words leading to emphatic writing– Use specific and familiar words, it make for clearer reader (and

writing)– It is OK if you reuse a word if it means you are avoiding

generalities/ambiguities– Don't use words that you don't know– Never use slang words in technical writing

25

9. Qualifiers and Padding

• Qualifiers:– Might, may, perhaps, possibly, likely, likelihood, could– Use only once per sentence– Double negatives are a form of qualifier

• Merten's algorithm is not dissimilar to ours

• Padding– Use of phrases like 'the fact that', 'of course', 'in

general' should be avoided.– Introduction of quantities: 'a number of' instead of

'several'

26

10. Misused words

27

10. Misused words (continued)• Which, that, the

– There is one method which is acceptable– There is one method that is acceptable

• May (personal choice), might , can (ability)• Less (continuous quantities), fewer (discrete quantities)• Affect (causing effect), effect(consequence)• Alternate (one or the other), alternative (one or any of a set of others), choice• Basic (elementary), fundamental, sophisticated (not new)• Conflate (regards distinct as similar), merge (join distinct to form new)• Continual (without stop), continuous (unbroken)• Conversely (opposite), similar, likewise (parallel)• Fast (quickly), quickly, presently (soon), timely (opportune), currently (at

present)

28

11. Spelling conventions, Jargon, Foreign words, and overuse of words

• Spelling conventions– UK vs US spelling, ize, yse, center, centre, and more– Be consistent, lookup the countries dictionary

• Jargon– Avoid but some times difficult not to use. Be consistent

• Foreign words– Some think it adds pizzazz to the article; don't use weird characters (ầ)

• Overuse of words– Some words are memorable and can be spotted (this, very also)– Also tics 'so', 'also', 'hence', 'thus' and 'note that'– More memorable words should only be used once

29

12. Redundancy

and wordiness• Use the minimum

number of words with minimal words for your writing

30

13. Tense, Plurals, Abbreviations

• Tense– Most technical work contained part and present– Present is for truths and the text itself– Past tense is used for describing work and outcomes– Future tense used only for conclusions

• Plurals– When describing classes don’t use excessive plurals, consider rephrasing– Variant plurals are slowly becoming less common: Formulas instead of

formulae, indexes instead of indices • Abbreviations

– Non native speakers might find them difficult– No. (number) – i.e. (that is) – e.g. (for example) – c.f. (in contrast to) – w.r.t.

(with respect to), use them with correct punctuation

31

14. Acronyms and Sexist language

• Acronyms– explain them the first time, don't use full stops– CPU, not C.P.U. or CPU. – Don't introduce them unless they are frequent

• Sexist language– Try and avoid gendering your text; – rephrase by either using 'they' or – rephrase all together

32

End summary

• Writing style– General guidelines– Specific instructions of do's and don'ts relating to• Titles and headings, Structure, paragraphs• Sentences, Wording, misused words• Abbreviations, Acronyms• Tense, spelling conventions, definitions• Ambiguity, emphasis • Rrepetitions and paralleisms