A talk in Yahoo how to write sample code and examples that make people want to use your technology. Audio is available at archive.org: http://www.archive.org/details/GivingTechnologyToTheWorld

1. Giving technology
to the world.
Advoca4ng, Showcasing and Explaining
Chris4an Heilmann, Yahoo internal talk, Sunnyvale, California, 04/02/2010

2. Disclaimer:
I will in this presenta4on complain about some
examples that are live on web sites.
I do this cause I have a chance to change them
and to encourage us to do beKer.
I do realise that it is easy to judge decisions with
the benefit out hindsight ‐ but this is not an
excuse to repeat mistakes of the past.
Complacency is the enemy of innova4on and
communica4on.

3. Wri4ng great technology is
a thing good developers
do.

4. Explaining the technology
to others, making it
understandable and
maintainable is a totally
different thing.

5. There are a few things that
make a developer a bad
advocate of technology.

6. 1. We know the subject maKer.
2. We are not known for our
pa4ence.
3. We have to go through a lot of
pain and see this as a useful
learning experience for
everybody.
4. This is all so obvious! Good code
explains itself!

7. On the other hand, sales
and marke4ng people are
bad tech advocates.

8. 1. The brand and our product comes
first.
2. There is a good and posi4ve story
in everything.
3. It is about the fun, connec4ng
with other people and doing like
cool tech stuff ‐ and like, other
stuff.
4. There is no compe44on!

9. Good tech advocacy is a
mashup.

10. To succeed in giving tech to
the world you have to
change your approach.
Here’s a problem
Use this!
and this is a
It rocks!
solu4on.

11. The main thing to answer
to any end user and
developer out there is:
What is in it for me?

12. Developers are busy
people and don’t have
4me to read long
documents.

13. Detailed documenta4on is
needed, but is only used
when things already went
wrong.

14. In order to get people to
care and get them to play
with what you offer, you
need a simple way in.

15. Some examples.

16. hKp://keywordfinder.org/

17. hKp://icant.co.uk/geomaker/index.php

18. hKp://isithackday.com/hacks/placemaker/tweet‐loca4ons.php

19. hKp://icant.co.uk/goohoobi/index.php?research

20. hKp://developer.yahoo.com/yui/grids/builder/

21. hKp://developer.yahoo.com/yui/grids/builder/

22. hKp://developer.yahoo.com/yui/ar4cles/hos4ng/#configure

23. YQL hKp://developer.yahoo.com/yql/console/

24. Bring the data out into the
open ‐ as soon as possible.

26. Keep the eye on the end
result and explain the way
to get there.

29. This expects me to
download the SDK, get an
authen4ca4on code ,
authen4cate and then I get
some data.

30. The data, however doesn’t
need any authen4ca4on.
select * from flickr.photos.search w
here text="panda" limit 3
select * from rss where url=”hKp://
rss.news.yahoo.com/rss/
topstories” and 4tle like "%China%"

31. This is a common error ‐
packing too much
informa4on into an
example.

32. Using YQL is easy! (PHP)

33. Using YQL is easy! (JavaScript)

34. Explain the way to the
data , don’t try to get it all
done in one step.

35. An4cipate stumbling
blocks, and write the story
to the full results.
• Here’s how to get public data.
• Here’s how to get private data.
• Here’s how to use the returned
informa4on.

37. hKp://maps.google.com/maps/api/sta4cmap?
sensor=false&size=300x300&maptype=roadmap
&markers=color:blue|label:I|37.4225,‐122.14246
&key={MAPKEY}

40. Know your environment.

42. Know your environment.
• Write defensive code
• Check online status
• List dependencies very early
• Provide a build and test script
• Provide a demo key

43. Make it easy to use your
code.
• Provide a live demo / show
screencast
• Provide a full download (GitHub)
• Offer hos4ng if needed
• Document full download and link
back to live example.

44. Write excellent copy and
paste code.
• Link all resources
• Provide the full script upfront
• Validate and secure your code
• Use best prac4ces

46. Bonus tricks:
• Show how your code plays well
with others (successful products)
• Give examples how using your
product made others successful
• Advocate maintainable and
reusable code with your
examples.

47. Sample code should be the
cleanest and best code you
ever write in your career.

48. Anything you do in sample
code will be used and
imitated.

49. If you do a good job, you
can help teach great
developers of tomorrow.

50. If you do a bad job, you
cause truisms, bad coding
prac4ces and fail at
advoca4ng yourself and
your company as thought
leaders.

51. The main trick to great
documenta4on and
examples is collabora4on.

52. Work with someone to ask
you the right ques4ons
and challenge you to
create a rock‐solid demo.

53. Chris4an Heilmann
hKp://wait‐4ll‐i.com
Thanks!
hKp://developer‐evangelism.com
hKp://twiKer.com/codepo8