Improving the quality of your written communication/High_quality_scientific... · Improving the...

Improving the quality of your written communicationprof. Gerald Q. Maguire Jr. http://web.ict.kth.se/~maguireSchool of Information and Communication Technology (ICT), KTH Royal Institute of TechnologyGraudate workshop 2014.04.26 © 2014 G. Q. Maguire Jr. All rights reserved.

Motivation

Jason Hong, “Ph.D. Students Must Break Away From Undergraduate Mentality”, CACM, 56(7):10-11, July 2013,doi: 10.1145/2483852.2483857In the section “Build Up Your Skills, but Get Out as Soon as You Can”:“Although computer science is quite diverse, the best Ph.D. students across all areas are actually quite similar. They are the ones who have solid critical thinking skills, a high degree of creativity, a strong work ethic, good writing and presentation skills, and a demonstrated ability to work independently with little supervision.”

2014.04.28 SLIDE 2WORKSHOP ON DOCTORAL EDUCATION AT ICT

#4

MotivationRichard Marchinko, Commander (Ret.) http://www.dickmarcinko.com/Default.aspx• U.S. Navy SEAL commander• First commanding officer of SEAL Team Six and Red Cell• Bronze Star with Valor Device and three Gold Stars, Legion of Merit, Silver Star, …• 4 non-fiction and 16 fiction “Rogue Warrior” books ⇒ Find a good co-author

Ten commandments: “1) I am the War Lord and the wrathful God of Combat and I will always lead you from the front - not the rear. 2) I will treat you all alike - just like s***. 3) Thou shalt do nothing I will not do first, and thus will you be created Warriors in My deadly image. 4) I shall punish thy bodies because the more thou sweatest in training, the less thou bleedest in combat. 5) Indeed, if thou hurteth in thy efforts and thou suffer painful dings, then thou are Doing It Right. 6) Thou hast not to like it - thou hast just to do it. 7) Thou shalt Keep It Simple, Stupid. 8) Thou shalt never assume. 9) Verily, thou art not paid for thy methods, but for thy results, by which meaneth thou shalt kill thine enemy by any means available before he killeth you. 10) Thou shalt, in thy Warrior's Mind and Soul, always remember My ultimate and final Commandment: There Are No Rules - Thou Shalt Win at All Costs.”

“Leadership Secrets of the Rogue Warrior”, ISBN-10: 0671545140, 1997


Communication tools & techniques

• Conference papers, Journal papers, …• Oral presentations and posters• Popular books, newspaper columns, …• Web sites, blogs, …• Open source code/hardware• Applications & Products• News releases• Podcasts, videos & multimedia presentations• Communicating with journalists, reporters, …


Get into the habit of reading

Regularly read books, journals, conference proceedings, …

Read criticallyWrite down the reference’s bibliographic

information and your notes• Use a reference manager, such as Zotero to help you• Could you find the reference again in 6 months, 1yr, … ?

If you cannot find it, how can your reader?• Organize the copies of what you read so that you can find

them again• “If you don’t write it down, it is gone!” -- Ted Nelson


Get into the habit of writing

Like any other skill, it takes ~104 hours to become expert

Some say that if you do not practice at least 4 hours per day you will neverbecome expert.

⇒ Write at least 1 draft page per day


Before we communicate, we need to have something to communicate

Doing your own work:

• Original research (conceive)• Development (design, implement, operate &

evaluate)Describing the results of yourself and/or others:• Patents• Review, survey, and scholarly articles• Books: textbooks, professional literature, …• Popular press/media


Identify who is your audience

Given this audience:What do they already know? (limitations)Who do they need to know? (goals)What do they expect?What will make them interested in what you have to say? (i.e., what is their motivation)What do you want them to do after your presentation? (What do you expect?)


A cognitive model of writing process

1. Planning• Generating ideas• Organizing• Setting goals (generating subtasks)

2. TranslatingConverting the plans into text, pictures, …

3. Reviewing• Reading• Editing

2014.04.28 SLIDE 9

Mon

itorin

g

WORKSHOP ON DOCTORAL EDUCATION AT ICT

Writing strategies

Beethovian1. Write everything down2. Edit it

2014.04.28 SLIDE 10

Motzartian1. Compose everything in

your head2. Write it down


Mike Sharples’ external representation model: stages of planning and text producing

Uninstantiated InstantiatedUnorganized (1) Technique: Brainstorming

Representation: Idea-labels(2) Technique: Note-taking, collecting quotes

Representation: NotesNon-linear organization

(3) Techniques: Follow a thread, write as dialect

Representation: Network ofidea-labels

(4) Techniques: Organizing notes, filing

Representation: Network of Notes

Linear organization

(5) Technique: Linear planning

Representation: list of idea-labels, table of contents

(6) Techniques: Drafting test, revising text, copying text

Representation: Linear text

2014.04.28 SLIDE 11

Start in any box and follow any path that gets you to box (6).


Four things to think about when writing1. What you are saying?2. What you are going to

say?3. What will your reader

think when reading what you have written?

4. What do you want your reader to do after reading what you have written?

2014.04.28 SLIDE 12

Content

Structure & Argument

Communication

Effect


Writing for a thesis/dissertation

When you think of a question write it downWhen you think of an answer write it down

Reflect upon what you have written:• Look at your table of contents (at least once per week)• Read what you have written• Re-read and revise your abstract• Are you solving the problem(s) you intended to solve?

If you are planning a collection of papers style thesis, plan how the papers form a progression. (What should each accomplish?)


Writing papers for conference, journals, etc.

Plan• Selected your venue and your paper well in advance

• Have a clear purpose for your publication in this venue • Consider impact factor, selectivity, costs, …

• Know the dates (due date for conference and special issues; and date of the conference – you will need to be there)

Writing[Outline], Draft, then revise, (get feedback from your friends, revise)+

Target your writing to your target audience and use the correct template

Addressing Reviewer’s comments• Take advantage of this feedback• Know when to push back and when to accept


Choose your writing tool(s)

• Pencil/ Pen + paper• Emacs or other editor + LaTeX• Command line tools (spell checking, grammar checking)• What You See Is What You Get (WYSIWYG):

Microsoft Word, OpenOffice Writer, Adobe FrameMaker, …

• Use a tool to compare documents

See also Jeffrey Morgan, An Evaluation of Modern Writing Tools, Web page: Usability,etc.: Usability, interface design, human factors and other interactivegoodness, 2011, last accessed: 2011.08.15, http://usabilityetc.com/articles/modern-writing-tools-evaluation/


No matter what tool you use,learn to use it

Value your own time – investing a little time to learn how to use your tool well will save you lots of time (in the long run)

Avoid looking dumb – do not hurt yourself with your choice of tool


Finding sources and citing them

What have others done and how can you find, read, describe, and cite this work?Find suitable sources:

• Search engines (both via web and library)• Developing your reading habits: review

articles, journals, conference proceedings, books, …

• Following experts in the field• Asking others


What about Wikipedia?

Wikipedia is not a primary sourceWhat is a source?

• the work itself• author• publisher

Reliable source:• Published materials with a reliable publication

process• Authoritative author• Verifiable: following the citation you should be able to

find the source


Keeping track of your references

• BibTeX - www.bibtex.org• Zotero - www.zotero.org• Endnote - www.endnote.com/

A product of Thomson Reuters for Microsoft Windows and Apple Mac OS X

See also:Brian Croxall, Zotero vs. EndNote, The Chronicle of Higher Education,3 May 2011, 11:00 am, http://chronicle.com/blogs/profhacker/zotero-vs-endnote/33157


Zotero

A tool for collecting, maintaining, and utilzing referencesPlug-in for Firefox + plugin-ins for Microsoft Word, OpenOffice, … [Firefox has to be running while you work]Save your entries local or on a serverYou can import references• Add Item by Identifier: ISBN, DOI, or PMID• Import from a file (for example a BibTeX, RIS, Refer/BibIX, … formatted file) or from the

clipboard (which might contain an EndNote formatted entry)

Making a reference from current web page or manually write an entry+ PDF indexing (http://www.zotero.org/support/pdf_fulltext_indexing )Group libraries – providing shared access with your collaboratorsAdd citations to your document with the plug-ins for Microsoft Word or OpenOffice• choose and even change your choice of reference format and

citation format.


What to do when you locate a potential source

Read the abstract, conclusions, body, references, list of authors and their affiliations, …Write down all the necessary reference information, so that you can:

• Find this source again• Cite it - if you find it relevant

Write a summary of what you learned

For a web page it is essential to have the date of access or date of last modification in addition to the URL - as web page content can change with time (http://wayback.archive.org/web/)


Document processing (Microsoft Word, OpenOffice, LaTeX, …)

Make use of TemplatesMake use of Styles

Use the predefined styles (modify if necessary)Define new styles when needed – use logical names(for example; “Preface Heading 1”, rather than “18point Helvetica”)Note that for some purposes you may need to “tweak” the style to get exactly what a specific publisher wants.

Be organized and systematic in your naming of directories, files, pictures, tables, data files, … (just like you would when doing software development – you may even want to use version control software)


Presenting information with images

“A picture is worth a thousand words.”-- Popular saying

Pictures, graphs, flow charts, UML, state machines, … can convey an enormous amount of information if used well.

Consider “a wink” at a party


Edward Tufte's books

Examples of how to present information well and even beautifully:

Beautiful Evidence, Graphics Press, July 2006, 213 pages, ISBN-10: 0961392177, ISBN-13: 978-0961392178

The Visual Display of Quantitative Information, Graphics Press, May 2001, 200 pages, ISBN-10: 0961392142, ISBN-13: 978-0961392147

Visual Explanations: Images and Quantities, Evidence and Narrative, GraphicsPress, February 1997, 156 pages, ISBN-10: 0961392126, ISBN-13: 978-0961392123

Envisioning Information, Graphics Press, May 1990, 126 pages, ISBN-10: 0961392118, ISBN-13: 978-0961392116

http://www.edwardtufte.com/tufte/index


Use the icons relevant to your field

Network diagrams:Cisco’s Network Topology Icons are freely available for use when drawing network diagrams.

EPS, JPEG, PPT, and Visio formats:http://www.cisco.com/web/about/ac50/ac47/2.html


Some common mistakes: General

Incomplete references or missing important citationsPoor (or no) editing ⇒ you do not care enough to check what you wrote!• Failure to spell check the document• Documents which it is clear that no one looked at after formatting - often these have

breaks in the middle of sentences, missing phrases, ... .• Incorrect paper sizeSections and subsections are not numbered - hiding both the

structure of the document and making cross references difficultLack of vertical white space between paragraphs, makes it hard to

understand where new paragraphs begin (indent first line 2-3 em)Lack of a date - every document should have a dateLack of page numbers


Some more common mistakes: Writing

Statements made without justification or supporting citationsUse of contractionsUse of acronyms or abbreviations without properly introducing

them; often failure to use these acroynms and abbreviations consistently through the rest of the paper

Redundant textUsing too few refences, often the paper looks like simply a cut

and paste edit of these few references.Single sentence paragraphsNot using primary sources when possibleNot using cross references effectively – for example not

referencing your figures, tables, code examples, …Not using your tools effectively!


Some common mistakes: Figures

Using figures from others without the copyright owner's permission

Unreadable text in figuresFailure to label elements of figures adequatelyFailure to use generally understood iconsPoor or missing figure captions – explain what the figure

shows (imagine someone who is blind who depends upon your caption to explain what the picture shows)

Using a poor choose of colors and not also using different stipple patterns/styles/… (Keep in mind the readers who are color blind)


Poster presentations

A chance to talk to one or a small number of people while standing at your poster or for your poster to be viewed both others without you.

typically A0 (841 by 1,189 millimetres(33.1 × 46.8 inches) in size – this is 1 m2

Title, authors, affiliations, abstract, body (Introduction, Materials and Methods, Results, Conclusions), and references.

Body includes pictures, plots, tables, …Poster may also have logos – be sure to check the rules of your organization

if you use logos.See http://intra.kth.se/en/regelverk/policyer/grafisk-profil/mallar/2.15960/mall-

for-vetenskapliga-posters-1.40309


Learning

To move from novice learner to expert learner requires applying three principles: Intentionality – attention and deliberationReflection – thinking about what worked, what did not work and whyAccountability – being responsible for what you do, say, write, …

Mark Sample, “Learning Through Digital Media: Sharing Research and Building Knowledge through Zotero”, Blog entry, Learning Through Digital Media: Experiments in Technology and Pedagogy as part of

Mobility Shifts: an International Future of Learning Summit (editor R. Trebor Scholz), http://learningthroughdigitalmedia.net/sharing-research-and-building-

knowledge-through-zotero


Artisan versus Virtuoso

From artisan (highly competent experts) to virtuoso (going beyond what they already expertly know to push the state of the art ⇒knowing which rules to break)⇒ Use metacognition to become an expert

see page 50, in Chapter 2: How Experts Differ from Novices, in John Bransford, Ann L. Brown, and Rodney R. Cocking (Editors), How people

learn: brain, mind, experience, and school, Expanded ed., Commission on Behavioral and Social Sciences and Education, National Research

Council,National Academy Press, Washington D.C., USA, 2000,ISBN 978-0-309-07036-2,

http://books.nap.edu/catalog.php?record_id=9853


Conclusions

Be your own best critic – reflect on your own writing and speaking to identify what you did well and did not do well ⇒learn from your experience.

Learn from others – be open to constructive criticismHelp others to improve (Pay it forward!)Carefully select your toolsLearn to use your tools well (and safely)When you truly master the tool, then you can “make” it do what you need to do.(read, write, reflect, edit)n

You may even need to rewrite to have just the right layout (see Donald Knuth’s The Art of Computer Programming, Volumes 1, 2, and 3) ⇒ improving your reader’s experience


Some of my related lecture notes

Writing powertoolshttp://www.ict.kth.se/courses/II2202/Lecture5-Maguire-20130909a.pdf

Writing: Common mistakes and Oral presentation techniqueshttp://www.ict.kth.se/courses/II2202/Lecture7-Maguire-20130912.pdf


¿Questions?


Extra material + examples of more tools


IguanaTex: Latex Add-In for PowerPoint

2014.04.28 SLIDE 36

\documentclass{article}\usepackage{amsmath}\pagestyle{empty}\begin{document}

\begin{equation*}D(u,v) = \begin{pmatrix}1 & 0 & -u & u \cr 0 & 1& -v & v \cru & v & 1 - \frac{(u^2 + v^2)}{2} & \frac{(u^2 + v²)}{2} \cr u & v &- \frac{(u^2 + v^2)}{2} & 1+ \frac{(u^2 + v^2)}{2}\end{pmatrix}.\end{equation*}

\end{document}You can get it from http://www.technion.ac.il/~zvikabh/software/iguanatex/


Spelling and grammar tools

Spell checkers: GNU Aspell, ispell, Word’s built in spelling checking

Writer's Workbench (WWB) diction and style program http://www.gnu.org/software/diction/diction.html

See also Chapter 11: Grammar and Reference, in Michael Stutz. The Linux cookbook : tips and techniques for everyday use. 2nd ed. San Francisco: No Starch Press; 2004, ISBN-13: 978-1593270315. 829 pages.


WWB diction + style http://www.gnu.org/software/diction/diction.html

Saved your document as a text file (.txt)

Grammar checkinglinux> diction xxxx.txt

Checking for readabilitylinux> style Task_1-Project_Plan_Template-20110805.txtreadability grades:

Kincaid: 8.2ARI: 8.8Coleman-Liau: 11.2Flesch Index: 60.7/100 (plain English)Fog Index: 11.0Lix: 40.6 = school year 6SMOG-Grading: 10.5


Roughly indicates US grade level

Automated readability index

WWB style (continued)

sentence info:4122 characters830 words, average length 4.97 characters = 1.56 syllables61 sentences, average length 13.6 words44% (27) short sentences (at most 9 words)11% (7) long sentences (at least 24 words)1 paragraphs, average length 61.0 sentences14% (9) questions52% (32) passive sentenceslongest sent 50 wds at sent 11; shortest sent 1 wds at sent 4

word usage:verb types:to be (44) auxiliary (27)types as % of total:

conjunctions 4% (33) pronouns 4% (37) prepositions 9% (76)nominalizations 3% (27)

sentence beginnings:pronoun (6) interrogative pronoun (6) article (4)subordinating conjunction (2) conjunction (0) preposition (0)


More tools for charts, diagrams, etc.

Microsoft’s VisioDIA - http://live.gnome.org/DiaOpenOffice Draw http://www.openoffice.org/product/draw.html

or http://www.libreoffice.org/features/draw/ see “Opensource alternative to Microsoft Visio – LibreOffice Draw http://smacak.wordpress.com/2011/01/26/opensource-alternative-to-microsoft-visio

UML• StarUML™ - The Open Source UML/MDA Platform

http://staruml.sourceforge.net/en/• ArgoUML http://argouml.tigris.org/

yWorks' yEd Graph Editor http://www.yworks.com/en/products_yed_about.html

• CadSoft EAGLE http://www.cadsoftusa.com/


References1. Dennis Meredith, Explaining Research: How to reach key audience to advance your work, Oxford University Press, 2010,

ISBN 978-0-19-973205-02. OOoLatex Home Page, Last update 15 November 2007, http://ooolatex.sourceforge.net/3. Brian Croxall, Zotero vs. EndNote, The Chronicle of Higher Education, 3 May 2011, 11:00 am,

http://chronicle.com/blogs/profhacker/zotero-vs-endnote/331574. Julie Meloni, “Using Mendeley for Research Management”, A blog entry from ProfHacker - The Chronicle of Higher

Education,19 July 2010,http://chronicle.com/blogs/profhacker/using-mendeley-for-research-management/256275. Mark Sample, “Learning Through Digital Media: Sharing Research and Building Knowledge through Zotero”, Blog entry,

Learning Through Digital Media: Experiments in Technology and Pedagogy as part of Mobility Shifts: an International Future of Learning Summit (editor R. Trebor Scholz), http://learningthroughdigitalmedia.net/sharing-research-and-building-knowledge-through-zotero

6. John Bransford, Ann L. Brown, and Rodney R. Cocking (Editors), How people learn: brain, mind, experience, and school, Expanded ed., Commission on Behavioral and Social Sciences and Education, National Research Council,National Academy Press, Washington D.C., USA, 2000, ISBN 978-0-309-07036-2, http://books.nap.edu/catalog.php?record_id=9853

7. Jason Friedman. Zotero / BibTeX tips [Internet]. 2010 Mar 12 [cited 2011 Aug 15]; Available from: http://www.curiousjason.com/zoterotobibtex.html

8. Royce Kimmons. “Tutorial: Exporting Zotero to Excel”, March 26, 2010. http://kimmonsdesign.com/node/249. Robert Vesco. “Using R to Extract Excel/csv File of Citation Data from Zotero” July 15, 2011.

http://www.robertvesco.com/2011/07/technology/using-r-to-extract-excelcsv-file-of-citation-data-zotero.html10. Matthias Wjst. “PDF rename based on Zotero entry”, January 17, 2008. http://www.wjst.de/blog/blog/2008/01/17/pdf-

rename-based-on-zotero-entry/11. “Zotero Style Repository”, last access 2011.08.25, http://www.zotero.org/styles12. Cornelis Pieters. “Quick Start Guide for Creating Zotero Citation Styles”, June 26, 2011. http://www.condast.com/zotero/


References (continued)

13. Ron Galloway, Rethinking Powerpoint, last accessed 5 August 2011, http://www.galloway.tv/rethinking/rethinking.html14. Bob Grant, Pimp your PowerPoint, The Scientist, Volume 24, Issue 3, 1 March2010, Page 76, http://classic.the-

scientist.com/2010/3/1/76/1/15. Nancy Duarte, slide:ology: The Art and Science of Creating Great Presentations, O'Reilly Media, August 2008, 296

pages,Print ISBN: 978-0-596-52234-6, ISBN 10: 0-596-52234-7,Ebook ISBN: 978-0-596-55855-0, ISBN 10: 0-596-55855-4

16. Cliff Atkinson, Beyond Bullet Points: Using Microsoft PowerPoint to Create Presentations That Inform, Motivate, and Inspire, Microsoft Press, March 2005, 240 pages, ISBN-10: 0735620520, ISBN-13: 978-0735620520, http://www.sociablemedia.com/thebook.php4

17. Jeffrey Morgan, An Evaluation of Modern Writing Tools, Web page: Usability,etc.: Usability, interface design, human factors and other interactivegoodness, 2011, last accessed: 2011.08.15, http://usabilityetc.com/articles/modern-writing-tools-evaluation/

18. Princeton University "About WordNet." WordNet. Princeton University. 2010. http://wordnet.princeton.edu19. George A. Miller (1995). WordNet: A Lexical Database for English. Communications of the ACM Vol. 38, No. 11: 39-

41.20. Christiane Fellbaum (1998, ed.) WordNet: An Electronic Lexical Database. Cambridge, MA: MIT Press.21. Michael Stutz. Linux.com :: Improve your writing with the GNU style checkers [Internet]. 2006 Sep 7 [cited 2011 Aug

15]; Available from: http://www.linux.com/archive/articles/5683322. Cisco Corporate ID Dept , Cisco Network Topology Icons, Cisco Systems, Inc., June 8, 2011,

http://www.cisco.com/web/about/ac50/ac47/2.html23. smacak, “Opensource alternative to Microsoft Visio – LibreOffice Draw « Sasha’s weblog,” Opensource alternative to

Microsoft Visio – LibreOffice Draw, 26-Jan-2011. http://smacak.wordpress.com/2011/01/26/opensource-alternative-to-microsoft-visio/

24. ‘A Step-by-step Guide to Changing CSL Styles’, dev:citation_styles:style_editing_step-by-step [Zotero Documentation]. [Online]. Available: http://www.zotero.org/support/dev/citation_styles/style_editing_step-by-step. [Accessed: 25-August-2011].


Improving the quality of your written communication/High_quality_scientific... · Improving the...

Documents

Transcript of Improving the quality of your written communication/High_quality_scientific... · Improving the...