documenting first

Click here to load reader

Post on 06-May-2015

1.694 views

Category:

Technology

0 download

Embed Size (px)

DESCRIPTION

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.

TRANSCRIPT

  • 1.DocumentingFirst Brian Landau @brianjlandau http://claimid.com/brianjlandau

2. Who am IBrian Landau@brianjlandauhttp://claimid.com/brianjlandauDocumenting First DevNation SF - 8/14/2010 3. Who am I Viget LabsBrian Landau@brianjlandauhttp://claimid.com/brianjlandauDocumenting First DevNation SF - 8/14/2010 4. Who am I Viget Labs Rails & JavaScript Brian Landau@brianjlandauhttp://claimid.com/brianjlandauDocumenting First DevNation SF - 8/14/2010 5. Who am I Viget Labs Rails & JavaScript User Experience Brian Landau@brianjlandauhttp://claimid.com/brianjlandauDocumenting 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 GuidesDocumenting First DevNation SF - 8/14/2010 10. Types of Documentation API DocsNerds User GuidesDocumenting First DevNation SF - 8/14/2010 11. Types of Documentation API DocsNerds User Guides Suits Documenting First DevNation SF - 8/14/2010 12. Types of Documentation API DocsFor Open Source 13. DocumentationAPI or Driven Development 14. Ill just Document it Later 15. Why Focus on Documentation? 16. Audience Participation Things you Love / Hateabout 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. GoalMake it Fun Easy + to use 23. GoalMake it Fun Easy + to use 24. GoalMake 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 documentationDocumenting First DevNation SF - 8/14/2010 36. Joshua BlochsHow to Designa Good API and Why it Mattershttp://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 audienceDocumenting 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: jMappingvar data = [{ point: {lat: 43.65654, lng: -79.90138},name: "This Place", category: 'sample',info_html: "

Some stuff to display in the
First Info Window

" }];$.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}
History: ${history}", '${name}
');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/jmappinghttp://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.pdfhttp://vigetlabs.github.com/jmappingDocumenting First DevNation SF - 8/14/2010 64. The EndQuestions & CommentsRate it: http://spkr8.com/t/4288 http://pinboard.in/u:brianjlandau/t:devnation-sf/ Flickr Credits: clspeace Brian Landau peter_hasselbom @brianjlandau poportishttp://claimid.com/brianjlandau

View more