Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.

Technically speaking: How to Improve Your Code With Technical Writing

357 vues

Publié le

Well written instructions, informative comments throughout code, clearly scripted screencasts, and smart information architecture can take complex code and make it accessible to new developers. In the age of code sharing, this can be imperative to teaching the next generation of developers, passing along your code to successors, and help you better understand your own work.

Publié dans : Technologie
  • Soyez le premier à commenter

  • Soyez le premier à aimer ceci

Technically speaking: How to Improve Your Code With Technical Writing

  1. 1. @HeyAWhite Technically Speaking How to Improve Your Code With Technical Writing
  2. 2. @HeyAWhite //In today’s talk... Why is Writing Important What is Technical Writing Purpose Audience Deliverables 6 Tips for Effective Technical Writing
  3. 3. @HeyAWhite //what it’s not AP English
  4. 4. @HeyAWhite // You’re already a writer
  5. 5. @HeyAWhite //Technical Writing is not Hamlet To be, or not to be: that is the question: Whether ’tis nobler in the mind to suffer The slings and arrows of outrageous fortune, Or to take arms against a sea of troubles, And by opposing end them? To die: to sleep;
  6. 6. @HeyAWhite //Hamlet Translated Should I exist? Is it better to suffer a terrible situation or declare war on pain, and by doing that, dying. Sleeping.
  7. 7. @HeyAWhite //Hamlet Tech Style //Should I live? To be, or not to be: that is the question: //Or is it nobler to live and suffer? Whether ’tis nobler in the mind to suffer The slings and arrows of outrageous fortune, Or to take arms against a sea of troubles, //To fight the suffering, I must die And by opposing end them? To die: to sleep;
  8. 8. @HeyAWhite //why? why write?
  9. 9. @HeyAWhite //Writing helps you learn
  10. 10. @HeyAWhite //Writing helps you teach
  11. 11. @HeyAWhite //Writing makes you efficient
  12. 12. @HeyAWhite You. Must. Write.
  13. 13. @HeyAWhite //In today’s talk... Why is Writing Important What is Technical Writing Purpose Audience Deliverables 6 Tips for Effective Technical Writing
  14. 14. @HeyAWhite //overview what is technical writing?
  15. 15. @HeyAWhite //Technical Writing Example
  16. 16. @HeyAWhite //Technical Writing Example
  17. 17. @HeyAWhite Technical writing should not be sprinkles
  18. 18. @HeyAWhite //In today’s talk... Why is Writing Important What is Technical Writing Purpose Audience Deliverables 6 Tips for Effective Technical Writing
  19. 19. @HeyAWhite //purpose why you are writing
  20. 20. @HeyAWhite //Purpose: To Inform Overview of work Nitty gritty details
  21. 21. @HeyAWhite //Purpose: To Instruct Tutorials
  22. 22. @HeyAWhite //Purpose: To Inform Overview of work Nitty gritty details //Purpose: To Instruct Tutorials
  23. 23. @HeyAWhite //In today’s talk... Why is Writing Important What is Technical Writing Purpose Audience Deliverables 6 Tips for Effective Technical Writing
  24. 24. @HeyAWhite //audience who do we write for
  25. 25. @HeyAWhite //Present Me
  26. 26. @HeyAWhite //Future Me
  27. 27. @HeyAWhite //Colleagues & Replacements
  28. 28. @HeyAWhite //The World
  29. 29. @HeyAWhite //In today’s talk... Why is Writing Important What is Technical Writing Purpose Audience Deliverables 6 Tips for Effective Technical Writing
  30. 30. @HeyAWhite //deliverables types of writing
  31. 31. @HeyAWhite //Deliverable: Code Comments //Should I live? To be, or not to be: that is the question: //Or is it nobler to live and suffer? Whether ’tis nobler in the mind to suffer The slings and arrows of outrageous fortune, Or to take arms against a sea of troubles, //To fight the suffering, I must die And by opposing end them? To die: to sleep;
  32. 32. @HeyAWhite //Deliverable: Code Comments <!--block of episode content --> <div class="episode-block" id="post-5221"> <!-- episode image and guest name --> <a href="http://www.thirteen.org/openmind/distrust-but-verify/” title=""> <img src="opmd-distrust-mez.jpg" class="" alt=""> <div class="txtwrap cf"> <p class="guest">Jeremy Ben-Ami</p> </div> </a> </div> <!-- end episode -->
  33. 33. @HeyAWhite //Deliverable: Code Comments /***** Style the Episode Block *****/ .episode-block { position:relative; width:100%; max-width: 600px; a {display:block; position:relative; } /** absolute element needs a relative parent **/ img {position:relative; width:100%; height:auto;} .txtwrap {position:absolute; bottom: 0; left: 0; background:rgba(0,0,0,0.8);} /** position the text over the image, with a transparent black background **/ }
  34. 34. @HeyAWhite
  35. 35. @HeyAWhite //Deliverable: Code Comments // There are a lot of bananas, so to make it easier, here is a function that will find all of the bananas in the bunch and make the monkey eat them one by one foreach(banana b in bunch) { monkey.eat(b); //monkey eats one of the bananas } //there are no more bananas left, post monkey eating bananas
  36. 36. @HeyAWhite //Deliverable: Code Comments // Man with the Yellow Hat wants to distribute bananas foreach(banana b in bunch) { monkey.eat(b); //more than one causes stomach pain } //all bananas are eaten
  37. 37. @HeyAWhite //Remember to K.I.S.S.
  38. 38. @HeyAWhite //Deliverable: Readme
  39. 39. @HeyAWhite
  40. 40. @HeyAWhite //Deliverable: Tutorial
  41. 41. @HeyAWhite //Deliverable: Tutorial
  42. 42. @HeyAWhite //In today’s talk... Why is Writing Important Technical Writing 101 Purpose Audience Deliverables 6 Tips for Effective Technical Writing
  43. 43. @HeyAWhite //6 Tips for effective technical writing
  44. 44. @HeyAWhite //Tip be concise
  45. 45. @HeyAWhite //Tip be organized
  46. 46. @HeyAWhite //Tip be thorough
  47. 47. @HeyAWhite //Tip remember your audience
  48. 48. @HeyAWhite //Tip ask for feedback
  49. 49. @HeyAWhite //Tip work as you go
  50. 50. @HeyAWhite Technical Writing is like Funfetti
  51. 51. @HeyAWhite
  52. 52. @HeyAWhite Questions?

×