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