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

Documenting First

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.

Citation preview

Page 1: Documenting First

Documenting First

Brian Landau@brianjlandau

http://claimid.com/brianjlandau

Page 2: Documenting First

Documenting First DevNation SF - 8/14/2010

Who am I

Brian Landau@brianjlandau

http://claimid.com/brianjlandau

Page 3: Documenting First

Documenting First DevNation SF - 8/14/2010

Who am I

➡ Viget Labs

Brian Landau@brianjlandau

http://claimid.com/brianjlandau

Page 4: Documenting First

Documenting First DevNation SF - 8/14/2010

Who am I

➡ Viget Labs

➡ Rails & JavaScript

Brian Landau@brianjlandau

http://claimid.com/brianjlandau

Page 5: Documenting First

Documenting First DevNation SF - 8/14/2010

Who am I

➡ Viget Labs

➡ Rails & JavaScript

➡ User Experience

Brian Landau@brianjlandau

http://claimid.com/brianjlandau

Page 6: Documenting First

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/

Page 7: Documenting First

Documenting First DevNation SF - 8/14/2010

Types of Documentation

Page 8: Documenting First

Documenting First DevNation SF - 8/14/2010

Types of Documentation

➡API Docs

Page 9: Documenting First

Documenting First DevNation SF - 8/14/2010

Types of Documentation

➡API Docs➡User Guides

Page 10: Documenting First

Documenting First DevNation SF - 8/14/2010

Types of Documentation

➡API Docs➡User Guides

Nerds

Page 11: Documenting First

Documenting First DevNation SF - 8/14/2010

Types of Documentation

➡API Docs➡User Guides

NerdsSuits

Page 12: Documenting First

API Docs

Types of Documentation

For Open Source

Page 13: Documenting First

Documentation API

Driven Development

or

Page 14: Documenting First
Page 15: Documenting First

Document itI’ll just

Later

Page 16: Documenting First

Documentation?Why Focus on

Page 17: Documenting First

Love / Hate

Audience Participation

about Documentation

Things you

Page 18: Documenting First

Documenting First DevNation SF - 8/14/2010

Why focus on documentation?

Page 19: Documenting First

Documenting First DevNation SF - 8/14/2010

Why focus on documentation?

➡ Important for adoption by others

Page 20: Documenting First

Documenting First DevNation SF - 8/14/2010

Why focus on documentation?

➡ Important for adoption by others➡ Forces you to create a better end-

product

Page 21: Documenting First

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

Page 22: Documenting First

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

Page 23: Documenting First

+Fun EasyMake it

to use

Goal

Page 24: Documenting First

+Fun EasyMake it

to use

Goal

Page 25: Documenting First

+Fun EasyMake it

to use

Goal

Page 26: Documenting First

Fun Easy++

Page 27: Documenting First

Fun Easy++

Page 28: Documenting First

Fun Easy++

Page 29: Documenting First

Fun Easy++

Page 30: Documenting First

Documenting First DevNation SF - 8/14/2010

How

Page 31: Documenting First

Documenting First DevNation SF - 8/14/2010

How

➡ What are the use cases?

Page 32: Documenting First

Documenting First DevNation SF - 8/14/2010

How

➡ What are the use cases?

➡ How would you like to do that?

Page 33: Documenting First

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?

Page 34: Documenting First

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?

Page 35: Documenting First

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?

Page 36: Documenting First

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

Page 37: Documenting First

How to Designa Good API

and Why it Matters

Joshua Bloch’s

http://pinboard.in/u:brianjlandau/t:devnation-sf/

Page 38: Documenting First

Documenting First DevNation SF - 8/14/2010

Joshua Bloch's "Characteristics of a Good API"

Page 39: Documenting First

Documenting First DevNation SF - 8/14/2010

Joshua Bloch's "Characteristics of a Good API"

➡ Easy to learn

Page 40: Documenting First

Documenting First DevNation SF - 8/14/2010

Joshua Bloch's "Characteristics of a Good API"

➡ Easy to learn

➡ Easy to use, even without documentation

Page 41: Documenting First

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

Page 42: Documenting First

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

Page 43: Documenting First

Tips

Page 44: Documenting First

Tips

➡ Always have someone else look over it

Page 45: Documenting First

Tips

➡ Always have someone else look over it

➡ Don't document implementation

Page 46: Documenting First

Tips

➡ Always have someone else look over it

➡ Don't document implementation

➡ Concise/Clear/Complete

Page 47: Documenting First

Tips

➡ Always have someone else look over it

➡ Don't document implementation

➡ Concise/Clear/Complete

➡ "Mimic patterns in core APIs and language"

Page 48: Documenting First

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"

Page 49: Documenting First

jMapping

Example

Page 50: Documenting First

Example: jMapping

Page 51: Documenting First

Example: jMapping

Page 52: Documenting First

Example: jMapping

Page 53: Documenting First

Example: jMapping

Page 54: Documenting First

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

Page 55: Documenting First

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 />');

Page 56: Documenting First

Documenting First DevNation SF - 8/14/2010

Example: jMapping

$('#map').jMapping({ ... });

Page 57: Documenting First

Documenting First DevNation SF - 8/14/2010

Example: jMapping

http://vigetlabs.github.com/jmapping

http://pinboard.in/u:brianjlandau/t:devnation-sf/

Page 58: Documenting First

Final Tips

Page 59: Documenting First

Final Tips

➡ Start small and be succinct

Page 60: Documenting First

Final Tips

➡ Start small and be succinct

➡ Always review it with others

Page 61: Documenting First

Final Tips

➡ Start small and be succinct

➡ Always review it with others

➡ Don't implement too early

Page 62: Documenting First

Final Tips

➡ Start small and be succinct

➡ Always review it with others

➡ Don't implement too early

➡ Rewrite docs as changes happen

Page 63: Documenting First

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!

Page 65: Documenting First

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