Building a developer documentation wiki

Building a developer documentation wiki, by Sarah Maddox 1

Building a developer documentation wiki

Building a developer documentation wiki, by Sarah Maddox

The story

Wiki 1

XML

Temporary hosted site

Wiki 2

2


Let’s talk about

What developers want

Before and after

How we got to the “after”

Wiki and community

3


Single, dedicated site

Clear navigation

Simple start tutorials reference

Relevant search

Comments and contributions

What developers want

4


How we found out what they want

5


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


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


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


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


Conclusion

10

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

11


Campaign Monitor

Flickr

Google

Android

jQuery

More

Examples of respected documentation sites

12

See the references section at the end of the slide deck


Campaign Monitor

13


Campaign Monitor

14


Campaign Monitor

15


Campaign Monitor

16


Flickr

Real-time testing of the API

A “useful values” section

17


Flickr

18


Google

Overview of what’s possible

Standard code format

Good look

“Hello world” < 30 minutes

19


Google

20


Android

Cool look

Quick start

Introductory videos

Architectural outline

Plentiful examples

A one-stop shop

21


Android

22


jQuery

Parameter-determined behaviour

Contributions to the documentation

Permalinks

23


jQuery

24


Conclusion

25

Overview


Tutorial


Our basic structure confirmed:

25


Conclusion

26

Overview


Tutorial


Our basic structure confirmed:

26


Thinking about the big move...

Wiki 1

XML


Wiki 2

27


Before and after

28


Before

29


After

Zen Foundation

theme

30


After

Tech writer luv

31


After

Tech writer luv

32


Before

33


After

Navigation plugin

34


After

Generated ref docs

35


Before

36


After

Search plugin

37


Before

38


After

Feedback plugin

Answers plugin

39


How we got to the “after”

The migration – a story in itself

Customising the wiki

Iterative development – ongoing

40


The story of the migration

Wiki 1

XML


Wiki 2

41


9May

Request Wiki 2

26 Sep

Zen ready

28 Sep

AtlasCamp

Absolutedeadline

The migration

42


9May

26 Sep

Zen ready

28 Sep

AtlasCamp

Longwait

Absolutedeadline

Request Wiki 2

The migration

43


9May

26 Sep

Zen ready

28 Sep

AtlasCamp

Longwait

Absolutedeadline

Request Wiki 2

The migration

Confluence Hosted

44


Looking at the migration path again

Wiki 1

XML


Wiki 2

45


The real story

Wiki 1

XML


Wiki 2

46


9May

26 Sep

Zen ready

28 Sep

AtlasCamp

Longwait

Absolutedeadline

Request Wiki 2

Back to the timeline...

Confluence Hosted

47


9May

26 Sep

Zen ready

28 Sep

AtlasCamp

Longwait

Absolutedeadline

Usermanagement

Request Wiki 2

The migration

Confluence Hosted

48


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


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


9May

6 Sep

26 Sep

Zen ready

28 Sep

AtlasCamp

Usermanagement

Longwait

Absolutedeadline

31 Aug


1 Sep

Request Wiki 2

The migration

Confluence Hosted

51

Migrate docsfrom Wiki 1


9May

6 Sep

26 Sep

Zen ready

28 Sep

AtlasCamp

Usermanagement

Longwait

Absolutedeadline


1 Sep

Request Wiki 2

The migration

Confluence Hosted

52


8 Sep

Wiki 2 available

Wiki 2live

31 Aug


Longwait

9May

6 Sep

8 Sep

26 Sep

Zen ready

28 Sep

AtlasCamp

Usermanagement

Absolutedeadline

31 Aug


1 Sep

Deaddocs?

Request Wiki 2

Wiki 2 available

Wiki 2live

The migration

Confluence Hosted

53



9May

6 Sep

8 Sep

26 Sep

Zen ready

28 Sep

AtlasCamp

Usermanagement

Longwait

Absolutedeadline

31 Aug


1 Sep

Request Wiki 2

Wiki 2 available

Wiki 2live

The migration

Confluence Hosted

54



Broken hearts?

55


Broken links

56


Moral of the story

57



58



Zen theme

59



Zen theme

Navigation

Search

Forum panel

Feedback form

60



Zen theme

Navigation

Search

Forum panel

Feedback form

And more

61


Customisation summary

62


Iterative development

63


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


Designing the navigation

65


Designing the navigation

66


Designing the navigation – phase 1

67



68



69


Iterative development summary

70


Yaayyy trees


Wiki and community

72


Wiki and community

73

Community updates


Wiki and community

74

Community updates

Intellectual property


Wiki and community

75

Community updates


Comments and feedback


Wiki and community

76

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

77


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


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


Comments versus forum and form

80


Given a focus, people do awesome stuff

Doc sprints

81


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


In closing

Never-ending story

Documentation as conversation

Documentation as product

83


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

https://wikitechcomm.onconfluence.com/


Contacting me

Blog: http://ffeathers.wordpress.com

Email: [email protected]

Twitter: @sarahmaddox

http://twitter.com/sarahmaddox

LinkedIn: http://au.linkedin.com/in/sarahmaddox

Other blog: http://travellingworm.wordpress.com/

http://ffeathers.wordpress.com/

mailto:[email protected]

http://twitter.com/sarahmaddox

http://au.linkedin.com/in/sarahmaddox

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

86


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

Building a developer documentation wiki

Technology

Transcript of Building a developer documentation wiki