Documenting First

Documenting First Brian Landau @brianjlandau http://claimid.com/brianjlandau

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 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

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 Nerds ➡User Guides Documenting First DevNation SF - 8/14/2010

Types of Documentation ➡API Docs Nerds ➡User Guides Suits Documenting First DevNation SF - 8/14/2010

Types of Documentation API Docs For Open Source

Documentation API or Driven Development

I’ll just Document it Later

Why Focus on Documentation?

Audience Participation Things you Love / Hate about Documentation

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 Documenting First DevNation SF - 8/14/2010

Goal Make it Fun Easy + to use

Fun + Easy

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? ➡ Draft an API and some rough documentation Documenting First DevNation SF - 8/14/2010

Joshua Bloch’s How to Design a Good API and Why it Matters http://pinboard.in/u:brianjlandau/t:devnation-sf/

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 Documenting First DevNation SF - 8/14/2010

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"

Example jMapping

Example: jMapping

Example: jMapping var 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

Example: jMapping var data = [{ point: {lat: 43.65654, lng: -79.90138}, name: "This Place", category: 'sample', history: "Some History" }]; $.mapping(data, "${title} History: ${history}", '<a href="#${id}" class="map_item">${name}</a> '); 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/ Documenting First DevNation SF - 8/14/2010

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!

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

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

http://www.mefeedia.com	2
http://www.slideshare.net	1
http://spkr8.dev	1
http://speakerrate.com	1

Documenting First

by Brian Landau on Aug 15, 2010

Accessibility

Categories

Tags

Upload Details

Usage Rights

4 Embeds 5

Statistics

Documenting First — Presentation Transcript