View
3.172
Download
2
Category
Preview:
DESCRIPTION
Or, what developers want.
Citation preview
Slide 1Building a developer documentation wiki, by Sarah Maddox 1
Building a developer documentation wiki
Slide 2Building a developer documentation wiki, by Sarah Maddox
The story
Wiki 1
XML
Temporary hosted site
Wiki 2
2
Slide 3Building a developer documentation wiki, by Sarah Maddox
Let’s talk about
What developers want
Before and after
How we got to the “after”
Wiki and community
3
Slide 4Building a developer documentation wiki, by Sarah Maddox
Single, dedicated site
Clear navigation
Simple start tutorials reference
Relevant search
Comments and contributions
What developers want
4
Slide 5Building a developer documentation wiki, by Sarah Maddox
How we found out what they want
5
Slide 6Building a developer documentation wiki, by Sarah Maddox
Top 3 features/services to improve:
API documentation – 35.2%
Tutorials and code samples – 21.3%
Developer support and forums – 19%
Survey of development community
251 respondents
6
Slide 7Building a developer documentation wiki, by Sarah Maddox
Survey of development community
251 respondents
Other features/services to improve:
Plugin data storage
APIs
SDKs
:
Source availability
Marketing
Documentation is up there with the heavy-weights
7
Slide 8Building a developer documentation wiki, by Sarah Maddox
One-on-one discussions
Product managers interviewed the community developers
Informal internal poll
“What’s your favourite API doc site in the whole wide world?”
8
Slide 9Building a developer documentation wiki, by Sarah Maddox
Forums and blogs
Discussion on Stack Overflow
Flickr set by Pamela Fox
Blog post by Peter Gruenbaum
Article by Jacob Kaplan-Moss
Article by Alex Reisner
9
See the references section at the end of the slide deck
Slide 10Building a developer documentation wiki, by Sarah Maddox
Conclusion
10
Overview
Quick start, including installation
Tutorial(s)
Drill down to reference guides
A good structure for developer documentation
Slide 11Building a developer documentation wiki, by Sarah Maddox
If we don't get the documentation right
they will hate us
no matter what else we give them
11
Slide 12Building a developer documentation wiki, by Sarah Maddox
Campaign Monitor
Flickr
Android
jQuery
More
Examples of respected documentation sites
12
See the references section at the end of the slide deck
Slide 13Building a developer documentation wiki, by Sarah Maddox
Campaign Monitor
13
Slide 14Building a developer documentation wiki, by Sarah Maddox
Campaign Monitor
14
Slide 15Building a developer documentation wiki, by Sarah Maddox
Campaign Monitor
15
Slide 16Building a developer documentation wiki, by Sarah Maddox
Campaign Monitor
16
Slide 17Building a developer documentation wiki, by Sarah Maddox
Flickr
Real-time testing of the API
A “useful values” section
17
Slide 18Building a developer documentation wiki, by Sarah Maddox
Flickr
18
Slide 19Building a developer documentation wiki, by Sarah Maddox
Overview of what’s possible
Standard code format
Good look
“Hello world” < 30 minutes
19
Slide 20Building a developer documentation wiki, by Sarah Maddox
20
Slide 21Building a developer documentation wiki, by Sarah Maddox
Android
Cool look
Quick start
Introductory videos
Architectural outline
Plentiful examples
A one-stop shop
21
Slide 22Building a developer documentation wiki, by Sarah Maddox
Android
22
Slide 23Building a developer documentation wiki, by Sarah Maddox
jQuery
Parameter-determined behaviour
Contributions to the documentation
Permalinks
23
Slide 24Building a developer documentation wiki, by Sarah Maddox
jQuery
24
Slide 25Building a developer documentation wiki, by Sarah Maddox
Conclusion
25
Overview
Quick start, including installation
Tutorial
Drill down to reference guides
Our basic structure confirmed:
25
Slide 26Building a developer documentation wiki, by Sarah Maddox
Conclusion
26
Overview
Quick start, including installation
Tutorial
Drill down to reference guides
Our basic structure confirmed:
26
Slide 27Building a developer documentation wiki, by Sarah Maddox
Thinking about the big move...
Wiki 1
XML
Temporary hosted site
Wiki 2
27
Slide 28Building a developer documentation wiki, by Sarah Maddox
Before and after
28
Slide 29Building a developer documentation wiki, by Sarah Maddox
Before
29
Slide 30Building a developer documentation wiki, by Sarah Maddox
After
Zen Foundation
theme
30
Slide 31Building a developer documentation wiki, by Sarah Maddox
After
Tech writer luv
31
Slide 32Building a developer documentation wiki, by Sarah Maddox
After
Tech writer luv
32
Slide 33Building a developer documentation wiki, by Sarah Maddox
Before
33
Slide 34Building a developer documentation wiki, by Sarah Maddox
After
Navigation plugin
34
Slide 35Building a developer documentation wiki, by Sarah Maddox
After
Generated ref docs
35
Slide 36Building a developer documentation wiki, by Sarah Maddox
Before
36
Slide 37Building a developer documentation wiki, by Sarah Maddox
After
Search plugin
37
Slide 38Building a developer documentation wiki, by Sarah Maddox
Before
38
Slide 39Building a developer documentation wiki, by Sarah Maddox
After
Feedback plugin
Answers plugin
39
Slide 40Building a developer documentation wiki, by Sarah Maddox
How we got to the “after”
The migration – a story in itself
Customising the wiki
Iterative development – ongoing
40
Slide 41Building a developer documentation wiki, by Sarah Maddox
The story of the migration
Wiki 1
XML
Temporary hosted site
Wiki 2
41
Slide 42Building a developer documentation wiki, by Sarah Maddox
9May
Request Wiki 2
26 Sep
Zen ready
28 Sep
AtlasCamp
Absolutedeadline
The migration
42
Slide 43Building a developer documentation wiki, by Sarah Maddox
9May
26 Sep
Zen ready
28 Sep
AtlasCamp
Longwait
Absolutedeadline
Request Wiki 2
The migration
43
Slide 44Building a developer documentation wiki, by Sarah Maddox
9May
26 Sep
Zen ready
28 Sep
AtlasCamp
Longwait
Absolutedeadline
Request Wiki 2
The migration
Confluence Hosted
44
Slide 45Building a developer documentation wiki, by Sarah Maddox
Looking at the migration path again
Wiki 1
XML
Temporary hosted site
Wiki 2
45
Slide 46Building a developer documentation wiki, by Sarah Maddox
The real story
Wiki 1
XML
Temporary hosted site
Wiki 2
46
Slide 47Building a developer documentation wiki, by Sarah Maddox
9May
26 Sep
Zen ready
28 Sep
AtlasCamp
Longwait
Absolutedeadline
Request Wiki 2
Back to the timeline...
Confluence Hosted
47
Slide 48Building a developer documentation wiki, by Sarah Maddox
9May
26 Sep
Zen ready
28 Sep
AtlasCamp
Longwait
Absolutedeadline
Usermanagement
Request Wiki 2
The migration
Confluence Hosted
48
Slide 49Building a developer documentation wiki, by Sarah Maddox
9May
6 Sep
26 Sep
Zen ready
28 Sep
AtlasCamp
Usermanagement
Longwait
Planned exportfrom Wiki 1
Absolutedeadline
Request Wiki 2
The migration
Confluence Hosted
49
Slide 50Building a developer documentation wiki, by Sarah Maddox
9May
6 Sep
26 Sep
Zen ready
28 Sep
AtlasCamp
Usermanagement
Longwait
Absolutedeadline
1 Sep
Upgrade Wiki 1 to Confluence 4
Request Wiki 2
The migration
Confluence Hosted
50
Planned exportfrom Wiki 1
Slide 51Building a developer documentation wiki, by Sarah Maddox
9May
6 Sep
26 Sep
Zen ready
28 Sep
AtlasCamp
Usermanagement
Longwait
Absolutedeadline
31 Aug
Upgrade Wiki 1 to Confluence 4
1 Sep
Request Wiki 2
The migration
Confluence Hosted
51
Migrate docsfrom Wiki 1
Slide 52Building a developer documentation wiki, by Sarah Maddox
9May
6 Sep
26 Sep
Zen ready
28 Sep
AtlasCamp
Usermanagement
Longwait
Absolutedeadline
Upgrade Wiki 1 to Confluence 4
1 Sep
Request Wiki 2
The migration
Confluence Hosted
52
Migrate docsfrom Wiki 1
8 Sep
Wiki 2 available
Wiki 2live
31 Aug
Slide 53Building a developer documentation wiki, by Sarah Maddox
Longwait
9May
6 Sep
8 Sep
26 Sep
Zen ready
28 Sep
AtlasCamp
Usermanagement
Absolutedeadline
31 Aug
Upgrade Wiki 1 to Confluence 4
1 Sep
Deaddocs?
Request Wiki 2
Wiki 2 available
Wiki 2live
The migration
Confluence Hosted
53
Migrate docsfrom Wiki 1
Slide 54Building a developer documentation wiki, by Sarah Maddox
9May
6 Sep
8 Sep
26 Sep
Zen ready
28 Sep
AtlasCamp
Usermanagement
Longwait
Absolutedeadline
31 Aug
Upgrade Wiki 1 to Confluence 4
1 Sep
Request Wiki 2
Wiki 2 available
Wiki 2live
The migration
Confluence Hosted
54
Migrate docsfrom Wiki 1
Slide 55Building a developer documentation wiki, by Sarah Maddox
Broken hearts?
55
Slide 56Building a developer documentation wiki, by Sarah Maddox
Broken links
56
Slide 57Building a developer documentation wiki, by Sarah Maddox
Moral of the story
57
Slide 58Building a developer documentation wiki, by Sarah Maddox
Customising the wiki
58
Slide 59Building a developer documentation wiki, by Sarah Maddox
Customising the wiki
Zen theme
59
Slide 60Building a developer documentation wiki, by Sarah Maddox
Customising the wiki
Zen theme
Navigation
Search
Forum panel
Feedback form
60
Slide 61Building a developer documentation wiki, by Sarah Maddox
Customising the wiki
Zen theme
Navigation
Search
Forum panel
Feedback form
And more
61
Slide 62Building a developer documentation wiki, by Sarah Maddox
Customisation summary
62
Slide 63Building a developer documentation wiki, by Sarah Maddox
Iterative development
63
Slide 64Building a developer documentation wiki, by Sarah Maddox
Iterative development
1. Analyse
2. Mock up
3. Develop on test site
4. Use
5. Release
6. Get customer feedback
7. Go back to step 2
64
Slide 65Building a developer documentation wiki, by Sarah Maddox
Designing the navigation
65
Slide 66Building a developer documentation wiki, by Sarah Maddox
Designing the navigation
66
Slide 67Building a developer documentation wiki, by Sarah Maddox
Designing the navigation – phase 1
67
Slide 68Building a developer documentation wiki, by Sarah Maddox
Designing the navigation – phase 2
68
Slide 69Building a developer documentation wiki, by Sarah Maddox
Designing the navigation – phase 2
69
Slide 70Building a developer documentation wiki, by Sarah Maddox
Iterative development summary
70
Slide 71Building a developer documentation wiki, by Sarah Maddox 71
Yaayyy trees
Slide 72Building a developer documentation wiki, by Sarah Maddox
Wiki and community
72
Slide 73Building a developer documentation wiki, by Sarah Maddox
Wiki and community
73
Community updates
Slide 74Building a developer documentation wiki, by Sarah Maddox
Wiki and community
74
Community updates
Intellectual property
Slide 75Building a developer documentation wiki, by Sarah Maddox
Wiki and community
75
Community updates
Intellectual property
Comments and feedback
Slide 76Building a developer documentation wiki, by Sarah Maddox
Wiki and community
76
Community updates
Intellectual property
Comments and feedback
Doc sprints
Slide 77Building a developer documentation wiki, by Sarah Maddox
Is it safe?
Industry and environment
Authors
Monitoring by technical writers
RSS feeds
Wiki watches
You can all sleep sound tonightWe’re not crazy or anything
Open editing of wiki pages
77
Slide 78Building a developer documentation wiki, by Sarah Maddox
Permissions
All staff members can update the documentation
Other contributors sign a licence agreement first
Contributor licence agreement
Based on Apache Contributor License Agreement
Guards the rights of all
Wiki permissions and ACLA
78
Slide 79Building a developer documentation wiki, by Sarah Maddox
CC-by licence on all pages
Use our docs in any way you like
Acknowledge us as the source
Contributors know where they stand too
Creative Commons copyright licence
79
Slide 80Building a developer documentation wiki, by Sarah Maddox
Comments versus forum and form
80
Slide 81Building a developer documentation wiki, by Sarah Maddox
Given a focus, people do awesome stuff
Doc sprints
81
Slide 82Building a developer documentation wiki, by Sarah Maddox
This is the doc sprint presentations, right?
Doc sprint results
February 2010
23 sprinters (19 + 4)
19 tutorials, plus
November 2010
30 sprinters (16 + 14)
23 user guides
November 2011
17 sprinters (all internal)
11 tutorials
Yes, mate. We're going to talk about documentation for the next two hours.
It's going to be awesome!
82
Slide 83Building a developer documentation wiki, by Sarah Maddox
In closing
Never-ending story
Documentation as conversation
Documentation as product
83
Slide 84Building a developer documentation wiki, by Sarah Maddox
Wiki:
https://wikitechcomm.onconfluence.com
Amazon.com:
http://www.amazon.com/Confluence-Tech-Chocolate-Sarah-Maddox/dp/1937434001
XML Press:
http://xmlpress.net/publications/chocolate/
84
Confluence, Tech Comm, Chocolate A wiki as platform extraordinaire for technical communication
Slide 85Building a developer documentation wiki, by Sarah Maddox 85
Contacting me
Blog: http://ffeathers.wordpress.com
Email: sarah@atlassian.com
Twitter: @sarahmaddox
http://twitter.com/sarahmaddox
LinkedIn: http://au.linkedin.com/in/sarahmaddox
Other blog: http://travellingworm.wordpress.com/
Slide 86Building a developer documentation wiki, by Sarah Maddox
References
Atlassian Documentation Wiki, the original home of the documentation, and a relatively uncustomised wiki (Wiki 1): http://confluence.atlassian.com
Atlassian Developers site, the subject of the presentation (Wiki 2): http://developer.atlassian.com
Discussion on Stack Overflow: "Creating Great API Documentation: Tools and Techniques“ http://stackoverflow.com/questions/2001899/creating-great-api-documentation-tools-and-techniques
Flickr set from Pamela Fox showing the landing pages for various APIs, libraries and languages: http://www.flickr.com/photos/pamelafox/sets/72157626654131382/show/
“Web API Documentation Best Practices”, a blog post by Peter Gruenbaum: http://blog.programmableweb.com/2010/08/12/web-api-documentation-best-practices/
“Writing great documentation: What to write”, by Jacob Kaplan-Moss: http://jacobian.org/writing/great-documentation/what-to-write/
“A Standard for Open Source Code Documentation”, by Alex Reisner: http://code.alexreisner.com/articles/code-documentation-standard.html
86
Slide 87Building a developer documentation wiki, by Sarah Maddox
Examples of good developer docs
Campaign Monitor: http://www.campaignmonitor.com/api
Flickr: http://www.flickr.com/services/api/explore/?method=flickr.auth.checkToken
Google: http://code.google.com/apis/maps/documentation/javascript/
Full list of Google APIs: http://code.google.com/more/
Android: http://developer.android.com/index.html
jQuery: http://api.jquery.com
Rails Searchable API: http://railsapi.com/
Github: http://developer.github.com/
Oracle's Java API docs (originally from Sun): http://download.oracle.com/javase/1.5.0/docs/api/
87
Slide 88Building a developer documentation wiki, by Sarah Maddox 88
Recommended