Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Documenting First

2,735 views

Published on

As developers build new libraries and tools, they sometimes write documentation as an afterthought, or not at all. Poor or missing documentation can prevent a library from being adopted, and can also be the sign of a poor API.

This talk will look at the idea of documenting first, as a means of driving development. Documentation upfront means you end up with better documentation and better-designed APIs, which are two key elements to a library being heavily adopted.

Published in: Technology
  • Be the first to comment

Documenting First

  1. Documenting First Brian Landau @brianjlandau http://claimid.com/brianjlandau
  2. Who am I Brian Landau @brianjlandau http://claimid.com/brianjlandau Documenting First DevNation SF - 8/14/2010
  3. Who am I ➡ Viget Labs Brian Landau @brianjlandau http://claimid.com/brianjlandau Documenting First DevNation SF - 8/14/2010
  4. Who am I ➡ Viget Labs ➡ Rails & JavaScript Brian Landau @brianjlandau http://claimid.com/brianjlandau Documenting First DevNation SF - 8/14/2010
  5. Who am I ➡ Viget Labs ➡ Rails & JavaScript ➡ User Experience Brian Landau @brianjlandau http://claimid.com/brianjlandau Documenting First DevNation SF - 8/14/2010
  6. My Inspiration The Genesis and History of the Macintosh Project “ Writing manuals is a very special and privileged task in a computer company, for in the process of writing them you are forced to go over every detail of the hardware and software the company sells in an attempt to make it understandable and usable in our extremely broad customer base. In the process a consciencious writer will discover nearly every good and bad feature of the system, and can provide valuable feedback to the designers and implementers. -- Jef Raskin - Feb 16, 1981 http://pinboard.in/u:brianjlandau/t:devnation-sf/ Documenting First DevNation SF - 8/14/2010
  7. Types of Documentation Documenting First DevNation SF - 8/14/2010
  8. Types of Documentation ➡API Docs Documenting First DevNation SF - 8/14/2010
  9. Types of Documentation ➡API Docs ➡User Guides Documenting First DevNation SF - 8/14/2010
  10. Types of Documentation ➡API Docs Nerds ➡User Guides Documenting First DevNation SF - 8/14/2010
  11. Types of Documentation ➡API Docs Nerds ➡User Guides Suits Documenting First DevNation SF - 8/14/2010
  12. Types of Documentation API Docs For Open Source
  13. Documentation API or Driven Development
  14. I’ll just Document it Later
  15. Why Focus on Documentation?
  16. Audience Participation Things you Love / Hate about Documentation
  17. Why focus on documentation? Documenting First DevNation SF - 8/14/2010
  18. Why focus on documentation? ➡ Important for adoption by others Documenting First DevNation SF - 8/14/2010
  19. Why focus on documentation? ➡ Important for adoption by others ➡ Forces you to create a better end- product Documenting First DevNation SF - 8/14/2010
  20. Why focus on documentation? ➡ Important for adoption by others ➡ Forces you to create a better end- product ➡ Helps maintain clear purpose Documenting First DevNation SF - 8/14/2010
  21. Why focus on documentation? ➡ Important for adoption by others ➡ Forces you to create a better end- product ➡ Helps maintain clear purpose ➡ Helps you identify problem areas Documenting First DevNation SF - 8/14/2010
  22. Goal Make it Fun Easy + to use
  23. Goal Make it Fun Easy + to use
  24. Goal Make it Fun Easy + to use
  25. Fun + Easy
  26. Fun + Easy
  27. Fun + Easy
  28. Fun + Easy
  29. How Documenting First DevNation SF - 8/14/2010
  30. How ➡ What are the use cases? Documenting First DevNation SF - 8/14/2010
  31. How ➡ What are the use cases? ➡ How would you like to do that? Documenting First DevNation SF - 8/14/2010
  32. How ➡ What are the use cases? ➡ How would you like to do that? ➡ What do you want to prevent users from doing? Documenting First DevNation SF - 8/14/2010
  33. How ➡ What are the use cases? ➡ How would you like to do that? ➡ What do you want to prevent users from doing? ➡ How will others extend it? Documenting First DevNation SF - 8/14/2010
  34. How ➡ What are the use cases? ➡ How would you like to do that? ➡ What do you want to prevent users from doing? ➡ How will others extend it? Documenting First DevNation SF - 8/14/2010
  35. How ➡ What are the use cases? ➡ How would you like to do that? ➡ What do you want to prevent users from doing? ➡ How will others extend it? ➡ Draft an API and some rough documentation Documenting First DevNation SF - 8/14/2010
  36. Joshua Bloch’s How to Design a Good API and Why it Matters http://pinboard.in/u:brianjlandau/t:devnation-sf/
  37. Joshua Bloch's "Characteristics of a Good API" Documenting First DevNation SF - 8/14/2010
  38. Joshua Bloch's "Characteristics of a Good API" ➡ Easy to learn Documenting First DevNation SF - 8/14/2010
  39. Joshua Bloch's "Characteristics of a Good API" ➡ Easy to learn ➡ Easy to use, even without documentation Documenting First DevNation SF - 8/14/2010
  40. Joshua Bloch's "Characteristics of a Good API" ➡ Easy to learn ➡ Easy to use, even without documentation ➡ Hard to misuse Documenting First DevNation SF - 8/14/2010
  41. Joshua Bloch's "Characteristics of a Good API" ➡ Easy to learn ➡ Easy to use, even without documentation ➡ Hard to misuse ➡ Appropriate to audience Documenting First DevNation SF - 8/14/2010
  42. Tips
  43. Tips ➡ Always have someone else look over it
  44. Tips ➡ Always have someone else look over it ➡ Don't document implementation
  45. Tips ➡ Always have someone else look over it ➡ Don't document implementation ➡ Concise/Clear/Complete
  46. Tips ➡ Always have someone else look over it ➡ Don't document implementation ➡ Concise/Clear/Complete ➡ "Mimic patterns in core APIs and language"
  47. Tips ➡ Always have someone else look over it ➡ Don't document implementation ➡ Concise/Clear/Complete ➡ "Mimic patterns in core APIs and language" ➡ "Obey standard naming conventions"
  48. Example jMapping
  49. Example: jMapping
  50. Example: jMapping
  51. Example: jMapping
  52. Example: jMapping
  53. Example: jMapping var data = [{ point: {lat: 43.65654, lng: -79.90138}, name: "This Place", category: 'sample', info_html: "<p>Some stuff to display in the<br />First Info Window</p>" }]; $.mapping(data); Documenting First DevNation SF - 8/14/2010
  54. Example: jMapping var data = [{ point: {lat: 43.65654, lng: -79.90138}, name: "This Place", category: 'sample', history: "Some History" }]; $.mapping(data, "${title}<br />History: ${history}", '<a href="#${id}" class="map_item">${name}</a><br />'); Documenting First DevNation SF - 8/14/2010
  55. Example: jMapping $('#map').jMapping({ ... }); Documenting First DevNation SF - 8/14/2010
  56. Example: jMapping http://vigetlabs.github.com/jmapping http://pinboard.in/u:brianjlandau/t:devnation-sf/ Documenting First DevNation SF - 8/14/2010
  57. Final Tips
  58. Final Tips ➡ Start small and be succinct
  59. Final Tips ➡ Start small and be succinct ➡ Always review it with others
  60. Final Tips ➡ Start small and be succinct ➡ Always review it with others ➡ Don't implement too early
  61. Final Tips ➡ Start small and be succinct ➡ Always review it with others ➡ Don't implement too early ➡ Rewrite docs as changes happen
  62. Final Tips ➡ Start small and be succinct ➡ Always review it with others ➡ Don't implement too early ➡ Rewrite docs as changes happen ➡ Make it fun to use!
  63. Links http://pinboard.in/u:brianjlandau/t:devnation-sf/ http://www.azarask.in/blog/post/macintosh-project-genesis-and- history-16-feb-1981/ http://research.google.com/pubs/archive/32713.pdf http://vigetlabs.github.com/jmapping Documenting First DevNation SF - 8/14/2010
  64. The End Questions & Comments Rate it: http://spkr8.com/t/4288 http://pinboard.in/u:brianjlandau/t:devnation-sf/ Flickr Credits: • clspeace Brian Landau • peter_hasselbom @brianjlandau • poportis http://claimid.com/brianjlandau

×