1 / 32

Writing style guidelines

Writing style guidelines. By Andreas Grondoudis. 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

ordell
Download Presentation

Writing style guidelines

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript


  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

More Related