Writing style guidelines

1. Writing styleguidelines 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

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