Effective Writing-Key Skills for Computer Science-Lecture 05 Slides-Computer Science, Slides of Computer Science

Download Effective Writing-Key Skills for Computer Science-Lecture 05 Slides-Computer Science and more Slides Computer Science in PDF only on Docsity! Key  Skills  for Computer  Science Lecture  5:  Effec9ve  Wri9ng Michael  Wooldridge (mjw @ liv.ac.uk) Wri9ng  in  a  Technical  Work  Environment • Informal: • email • post-­‐it  notes • Formal: 2 The  9/11  Commission  Report • The  report  aCracted  a  good  deal  of  interest  at  the  Dme  not   just  because  of  how  important  the  subject  maCer  was,  but   because  of  the  style • AIer  reading  that  introducDon: • who  do  you  think  the  report  was  aimed  at? • do  you  think  this  made  the  report  more  or  less  successful? • what  are  the  dangers  in  using  such  a  style? 5 (Some)  Golden  Rules  of   Technical  Wri9ng 6 Golden  Rule  #1:   The  Aim  is  to  Communicate;   Everything  Else  is  Secondary • A  piece  of  technical  wriDng  will  be  judged  on  how  effecDvely  it   communicates  its  message • Anything  which  helps  communicate  the  message  is  good;  anything   that  gets  in  the  way  is  bad • Things  that  might  help: • examples,  diagrams,  explanatory  notes • Things  that  might  get  in  the  way: • bad  punctuaDon,  illogical  structure,  bad  spelling,  cliches,  obscure   terminology,  ... 7 Golden  Rule  #2:   Know  Your  Audience • Suppose  you  are  wriDng  safety  regulaDons  for  a  university,  to  be  read   by  1st  year  undergraduates  -­‐-­‐  which  of  the  following  newspaper  styles   would  you  suggest  to  adopt? • The  Times • The  Guardian • The  Financial  Times • The  Daily  Mirror • The  Daily  Mail • The  Telegraph • Now  suppose  the  regulaDons  are  to  be  read  by  academics  -­‐-­‐  which   style  might  be  most  appropriate  for  them? 10 Golden  Rule  #3:   Know  What  you  Want  to  Say • A  key  problem  in  many  scienDfic  papers  is  that  it  is  not  at   all  clear  what  message  the  authors  are  trying  to  get  across • It  may  help  to  simply  write  down  in  bullet  point  form  the   main  things  you  want  to  get  across  in  your  document • These  can  then  help  you  in  structuring  the  document 11 Golden  Rule  #4:   DraT;  Proof  Read;  Edit;  Proof  Read;  Edit;   Proof  Read;  Edit;  Proof  Read;  ... • “Easy  reading  is  damn  hard  wriDng”  (Nathaniel  Hawthorne) • The  only  way  you  will  succeed  to  write  effecDve  documents  is  to  go   through  a  series  of  edits • generate  a  first  draI,  and  print  (you  can’t  proof  read  on  screen) • “red  ink”  it  -­‐-­‐  proof  read  and  mark  up  with  correcDons,  in  red  ink   -­‐-­‐  correct  typos,  rewrite,  restructure,  ...   • edit  it  according  to  your  proof  read  copy • goto  (1) • Reading  it  out  loud  is  the  single  most  effecDve  way  to  tell  whether   its  good  or  not 12 Golden  Rule  #7:   No  Jokes •  (ACempts  at)  humour  are  simply  best  avoided  in  technical   documents • Somebody  will  always  misinterpret • Jokes  that  are  funny  for  white  English  males  won’t  be  for   anybody  else 15 Golden  Rule  #7:   Avoid  Local  References •  Technical  documents  are  typically  read  by  an  internaDonal   audience • Local  references  (eg  to  local  poliDcians,  football  clubs,  pop   stars,  TV  shows,  ...)  should  be  avoided  -­‐-­‐  they  don’t  travel   well 16 Golden  Rule  #8:   You  Can  Never  Have  Too  Many  Examples • By  far  the  best  way  to  explain  definiDons,  concepts,  etc  is   with  examples • In  general,  the  more  of  these  the  beCer • Start  with  very  simple  ones,  and  work  your  way  up 17 Golden  Rule  #11:   Be  Explicit • Subtlety  and  nuance  may  be  an  advantage  in  novels,  but  in   technical  documents  they  oIen  have  no  place • Be  explicit  and  straighborward  about  your  results  and  your   claims • (The  only  excepDon  is  where  you  are  talking  about   people...)       20 Golden  Rule  #999:  The  Rules  Don’t  Maeer • You  can  follow  all  the  rules  (of  grammar,  punctuaDon,   style,  ...)  and  sDll  write  nonsense;  you  can  ignore  them,  and   sDll  write  a  perfect  document • The  rules  are  not  the  point  of  the  exercise • The  point  of  the  exercise  is  to  communicate 21 Common  Technical  Documents • Scien2fic  papers: • aim  to  communicate  scienDfic  (research)  results  to  the  scienDfic  community • Proposals: • request  funds,  make  a  case  for  supporDng  something • EvaluaDons: • analyse  opDons  and  make  recommendaDons • Strategy/planning • propose  plans  and  courses  of  acDons • SWOT  analyses: • analyse  strengths,  weaknesses,  opportuniDes,  threats • Documenta2on: • document  the  workings  of  code  etc • Manuals: • aim  to  describe  how  to  use  a  piece  of  soIware/hardware 22