Building a developer documentation wiki

Building a developer documentation wiki, by Sarah Maddox 1

Building a developer documentation wiki, by Sarah Maddox

The story

Wiki 1

Temporary hosted site

Wiki 2

Let’s talk about

What developers want

Before and after

How we got to the “after”

Wiki and community

Single, dedicated site

Clear navigation

Simple start tutorials reference

Relevant search

Comments and contributions

What developers want

How we found out what they want

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

Survey of development community

251 respondents

Other features/services to improve:

Plugin data storage

Source availability

Marketing

Documentation is up there with the heavy-weights

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

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

See the references section at the end of the slide deck

Conclusion

Overview

Quick start, including installation

Tutorial(s)

Drill down to reference guides

A good structure for developer documentation

If we don't get the documentation right

they will hate us

no matter what else we give them

Campaign Monitor

Flickr

Google

Android

jQuery

Examples of respected documentation sites

See the references section at the end of the slide deck

Campaign Monitor

Flickr

Real-time testing of the API

A “useful values” section

Flickr

Google

Overview of what’s possible

Standard code format

Good look

“Hello world” < 30 minutes

Google

Android

Cool look

Quick start

Introductory videos

Architectural outline

Plentiful examples

A one-stop shop

Android

jQuery

Parameter-determined behaviour

Contributions to the documentation

Permalinks

jQuery

Conclusion

Overview

Tutorial

Our basic structure confirmed:

Conclusion

Overview

Tutorial

Our basic structure confirmed:

Thinking about the big move...

Wiki 1

Wiki 2

Before and after

Before

Zen Foundation

Tech writer luv

Before

Navigation plugin

Generated ref docs

Before

Search plugin

Before

Feedback plugin

Answers plugin

How we got to the “after”

The migration – a story in itself

Customising the wiki

Iterative development – ongoing

The story of the migration

Wiki 1

Wiki 2

Request Wiki 2

26 Sep

Zen ready

28 Sep

AtlasCamp

Absolutedeadline

The migration

26 Sep

Zen ready

28 Sep

AtlasCamp

Longwait

Absolutedeadline

Request Wiki 2

The migration

26 Sep

Zen ready

28 Sep

AtlasCamp

Longwait

Absolutedeadline

Request Wiki 2

The migration

Confluence Hosted

Looking at the migration path again

Wiki 1

Wiki 2

The real story

Wiki 1

Wiki 2

26 Sep

Zen ready

28 Sep

AtlasCamp

Longwait

Absolutedeadline

Request Wiki 2

Back to the timeline...

Confluence Hosted

26 Sep

Zen ready

28 Sep

AtlasCamp

Longwait

Absolutedeadline

Usermanagement

Request Wiki 2

The migration

Confluence Hosted

26 Sep

Zen ready

28 Sep

AtlasCamp

Usermanagement

Longwait

Planned exportfrom Wiki 1

Absolutedeadline

Request Wiki 2

The migration

Confluence Hosted

26 Sep

Zen ready

28 Sep

AtlasCamp

Usermanagement

Longwait

Absolutedeadline

Upgrade Wiki 1 to Confluence 4

Request Wiki 2

The migration

Confluence Hosted

Planned exportfrom Wiki 1

26 Sep

Zen ready

28 Sep

AtlasCamp

Usermanagement

Longwait

Absolutedeadline

31 Aug

Request Wiki 2

The migration

Confluence Hosted

Migrate docsfrom Wiki 1

26 Sep

Zen ready

28 Sep

AtlasCamp

Usermanagement

Longwait

Absolutedeadline

Request Wiki 2

The migration

Confluence Hosted

Wiki 2 available

Wiki 2live

31 Aug

Longwait

26 Sep

Zen ready

28 Sep

AtlasCamp

Usermanagement

Absolutedeadline

31 Aug

Deaddocs?

Request Wiki 2

Wiki 2 available

Wiki 2live

The migration

Confluence Hosted

26 Sep

Zen ready

28 Sep

AtlasCamp

Usermanagement

Longwait

Absolutedeadline

31 Aug

Request Wiki 2

Wiki 2 available

Wiki 2live

The migration

Confluence Hosted

Broken hearts?

Broken links

Moral of the story

Zen theme

Navigation

Search

Forum panel

Feedback form

Zen theme

Navigation

Search

Forum panel

Feedback form

And more

Customisation summary

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

Designing the navigation

Designing the navigation – phase 1

Iterative development summary

Yaayyy trees

Wiki and community

Community updates

Wiki and community

Community updates

Intellectual property

Wiki and community

Community updates

Comments and feedback

Wiki and community

Community updates

Comments and feedback

Doc sprints

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

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

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

Comments versus forum and form

Given a focus, people do awesome stuff

Doc sprints

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!

In closing

Never-ending story

Documentation as conversation

Documentation as product

https://wikitechcomm.onconfluence.com

Amazon.com:

http://www.amazon.com/Confluence-Tech-Chocolate-Sarah-Maddox/dp/1937434001

XML Press:

http://xmlpress.net/publications/chocolate/

Confluence, Tech Comm, Chocolate A wiki as platform extraordinaire for technical communication

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/

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

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/

Building a developer documentation wiki

Technology

Visualforce developer documentation

Developer API Documentation

PHPExcel AutoFilter Reference Developer Documentation

orbbec-astra-wiki Documentation

Moodle Developer documentation

Radeon Developer Panel Documentation

wiki Documentation

Abilian Developer Guide Documentation

GLPi Developer Documentation Documentation Release 0.1 Teclib

Spring Insight Developer - VMware Documentation

Open edX Developer Documentation

Brazil project Developer Documentation

Documentation Resources on the ESIP Wiki

Developer Documentation - General Electric

Documentation - .wiki

KDE Developer Documentation Update

PyQGIS developer cookbook - Documentation

XN3.wiki Documentation

Documentation OTRS 3.0 - Developer Manual

Designing Documentation for Developer Products