Documenting First
-
Upload
brian-landau -
Category
Technology
-
view
1.708 -
download
0
description
Transcript of Documenting First
Documenting First
Brian Landau@brianjlandau
http://claimid.com/brianjlandau
Documenting First DevNation SF - 8/14/2010
Who am I
Brian Landau@brianjlandau
http://claimid.com/brianjlandau
Documenting First DevNation SF - 8/14/2010
Who am I
➡ Viget Labs
Brian Landau@brianjlandau
http://claimid.com/brianjlandau
Documenting First DevNation SF - 8/14/2010
Who am I
➡ Viget Labs
➡ Rails & JavaScript
Brian Landau@brianjlandau
http://claimid.com/brianjlandau
Documenting First DevNation SF - 8/14/2010
Who am I
➡ Viget Labs
➡ Rails & JavaScript
➡ User Experience
Brian Landau@brianjlandau
http://claimid.com/brianjlandau
Documenting First DevNation SF - 8/14/2010
My Inspiration
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.
The Genesis and History of the Macintosh Project
“
-- Jef Raskin - Feb 16, 1981
http://pinboard.in/u:brianjlandau/t:devnation-sf/
Documenting First DevNation SF - 8/14/2010
Types of Documentation
Documenting First DevNation SF - 8/14/2010
Types of Documentation
➡API Docs
Documenting First DevNation SF - 8/14/2010
Types of Documentation
➡API Docs➡User Guides
Documenting First DevNation SF - 8/14/2010
Types of Documentation
➡API Docs➡User Guides
Nerds
Documenting First DevNation SF - 8/14/2010
Types of Documentation
➡API Docs➡User Guides
NerdsSuits
API Docs
Types of Documentation
For Open Source
Documentation API
Driven Development
or
Document itI’ll just
Later
Documentation?Why Focus on
Love / Hate
Audience Participation
about Documentation
Things you
Documenting First DevNation SF - 8/14/2010
Why focus on documentation?
Documenting First DevNation SF - 8/14/2010
Why focus on documentation?
➡ Important for adoption by others
Documenting First DevNation SF - 8/14/2010
Why focus on documentation?
➡ Important for adoption by others➡ Forces you to create a better end-
product
Documenting First DevNation SF - 8/14/2010
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
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
+Fun EasyMake it
to use
Goal
+Fun EasyMake it
to use
Goal
+Fun EasyMake it
to use
Goal
Fun Easy++
Fun Easy++
Fun Easy++
Fun Easy++
Documenting First DevNation SF - 8/14/2010
How
Documenting First DevNation SF - 8/14/2010
How
➡ What are the use cases?
Documenting First DevNation SF - 8/14/2010
How
➡ What are the use cases?
➡ How would you like to do that?
Documenting First DevNation SF - 8/14/2010
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
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
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
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
How to Designa Good API
and Why it Matters
Joshua Bloch’s
http://pinboard.in/u:brianjlandau/t:devnation-sf/
Documenting First DevNation SF - 8/14/2010
Joshua Bloch's "Characteristics of a Good API"
Documenting First DevNation SF - 8/14/2010
Joshua Bloch's "Characteristics of a Good API"
➡ Easy to learn
Documenting First DevNation SF - 8/14/2010
Joshua Bloch's "Characteristics of a Good API"
➡ Easy to learn
➡ Easy to use, even without documentation
Documenting First DevNation SF - 8/14/2010
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
Joshua Bloch's "Characteristics of a Good API"
➡ Easy to learn
➡ Easy to use, even without documentation
➡ Hard to misuse
➡ Appropriate to audience
Tips
Tips
➡ Always have someone else look over it
Tips
➡ Always have someone else look over it
➡ Don't document implementation
Tips
➡ Always have someone else look over it
➡ Don't document implementation
➡ Concise/Clear/Complete
Tips
➡ Always have someone else look over it
➡ Don't document implementation
➡ Concise/Clear/Complete
➡ "Mimic patterns in core APIs and language"
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"
jMapping
Example
Example: jMapping
Example: jMapping
Example: jMapping
Example: jMapping
Documenting First DevNation SF - 8/14/2010
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
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
Example: jMapping
$('#map').jMapping({ ... });
Documenting First DevNation SF - 8/14/2010
Example: jMapping
http://vigetlabs.github.com/jmapping
http://pinboard.in/u:brianjlandau/t:devnation-sf/
Final Tips
Final Tips
➡ Start small and be succinct
Final Tips
➡ Start small and be succinct
➡ Always review it with others
Final Tips
➡ Start small and be succinct
➡ Always review it with others
➡ Don't implement too early
Final Tips
➡ Start small and be succinct
➡ Always review it with others
➡ Don't implement too early
➡ Rewrite docs as changes happen
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!
Documenting First DevNation SF - 8/14/2010
Links
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
http://pinboard.in/u:brianjlandau/t:devnation-sf/
The EndQuestions & Comments
Brian Landau@brianjlandau
http://claimid.com/brianjlandau
http://pinboard.in/u:brianjlandau/t:devnation-sf/
Rate it: http://spkr8.com/t/4288
Flickr Credits:• clspeace• peter_hasselbom• poportis