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.
"I see eyes in my soup": How Delivery Hero implemented the safety system for ...
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
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
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/
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
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"
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
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!