Documenting First
•
6 j'aime•1,582 vues
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.
Recommandé
Recommandé
Contenu connexe
En vedette
Similaire à Documenting First
Similaire à Documenting First (20)
Dernier
Dernier (20)
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
- 15. I’ll just Document it Later
- 16. Why Focus on Documentation?
- 17. Audience Participation Things you Love / Hate about Documentation
- 18. Why focus on documentation? Documenting First DevNation SF - 8/14/2010
- 19. Why focus on documentation? ➡ Important for adoption by others 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 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 Documenting First DevNation SF - 8/14/2010
- 22. 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
- 23. Goal Make it Fun Easy + to use
- 24. Goal Make it Fun Easy + to use
- 25. Goal Make it Fun Easy + to use
- 26. Fun + Easy
- 27. Fun + Easy
- 28. Fun + Easy
- 29. Fun + Easy
- 30. How Documenting First DevNation SF - 8/14/2010
- 31. How ➡ What are the use cases? Documenting First DevNation SF - 8/14/2010
- 32. How ➡ What are the use cases? ➡ How would you like to do that? 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? 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? Documenting First DevNation SF - 8/14/2010
- 36. 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
- 37. Joshua Bloch’s How to Design a Good API and Why it Matters http://pinboard.in/u:brianjlandau/t:devnation-sf/
- 38. Joshua Bloch's "Characteristics of a Good API" Documenting First DevNation SF - 8/14/2010
- 39. Joshua Bloch's "Characteristics of a Good API" ➡ Easy to learn 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 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 Documenting First DevNation SF - 8/14/2010
- 42. 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
- 43. Tips
- 44. Tips ➡ Always have someone else look over it
- 45. Tips ➡ Always have someone else look over it ➡ Don't document implementation
- 46. Tips ➡ Always have someone else look over it ➡ Don't document implementation ➡ Concise/Clear/Complete
- 47. Tips ➡ Always have someone else look over it ➡ Don't document implementation ➡ Concise/Clear/Complete ➡ "Mimic patterns in core APIs and language"
- 48. 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"
- 49. Example jMapping
- 54. 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
- 55. 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
- 56. Example: jMapping $('#map').jMapping({ ... }); Documenting First DevNation SF - 8/14/2010
- 57. Example: jMapping http://vigetlabs.github.com/jmapping http://pinboard.in/u:brianjlandau/t:devnation-sf/ Documenting First DevNation SF - 8/14/2010
- 58. Final Tips
- 59. Final Tips ➡ Start small and be succinct
- 60. Final Tips ➡ Start small and be succinct ➡ Always review it with others
- 61. Final Tips ➡ Start small and be succinct ➡ Always review it with others ➡ Don't implement too early
- 62. Final Tips ➡ Start small and be succinct ➡ Always review it with others ➡ Don't implement too early ➡ Rewrite docs as changes happen
- 63. 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!
- 64. 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
- 65. 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