Building a developer documentation wiki

Building a developer documentation wikiBuilding a developer documentation wiki, by Sarah Maddox Slide 1 1

The storyWiki 1 XMLTemporary hosted site Wiki 2Building a developer documentation wiki, by Sarah Maddox Slide 2 2

Let’s talk about What developers want Before and after How we got to the “after” Wiki and communityBuilding a developer documentation wiki, by Sarah Maddox Slide 3 3

What developers want Single, dedicated site Clear navigation Simple start tutorials reference Relevant search Comments and contributionsBuilding a developer documentation wiki, by Sarah Maddox Slide 4 4

How we found out what they wantBuilding a developer documentation wiki, by Sarah Maddox Slide 5 5

Survey of development community 251 respondents Top 3 features/services to improve: API documentation – 35.2% Tutorials and code samples – 21.3% Developer support and forums – 19%Building a developer documentation wiki, by Sarah Maddox Slide 6 6

Survey of development community 251 respondents Documentation is up there with the heavy-weights Other features/services to improve: :  Plugin data storage  Source availability  APIs  Marketing  SDKsBuilding a developer documentation wiki, by Sarah Maddox Slide 7 7

One-on-one discussions Product managers interviewed the community developersInformal internal poll “What’s your favourite API doc site in the whole wide world?”Building a developer documentation wiki, by Sarah Maddox Slide 8 8

Forums and blogs  Discussion on Stack Overflow See the references section at the end  Flickr set by Pamela Fox of the slide deck  Blog post by Peter Gruenbaum  Article by Jacob Kaplan-Moss  Article by Alex ReisnerBuilding a developer documentation wiki, by Sarah Maddox Slide 9 9

Conclusion A good structure for developer documentation Overview Quick start, including installation Tutorial(s) Drill down to reference guidesBuilding a developer documentation wiki, by Sarah Maddox Slide 10 10

If we dont get the documentation right they will hate us no matter what else we give themBuilding a developer documentation wiki, by Sarah Maddox Slide 11 11

Examples of respected documentation sites  Campaign Monitor See the references section at the end  Flickr of the slide deck  Google  Android  jQuery  MoreBuilding a developer documentation wiki, by Sarah Maddox Slide 12 12

Campaign MonitorBuilding a developer documentation wiki, by Sarah Maddox Slide 13 13

Flickr  Real-time testing of the API  A “useful values” sectionBuilding a developer documentation wiki, by Sarah Maddox Slide 17 17

FlickrBuilding a developer documentation wiki, by Sarah Maddox Slide 18 18

Google  Overview of what’s possible  Standard code format  Good look  “Hello world” < 30 minutesBuilding a developer documentation wiki, by Sarah Maddox Slide 19 19

GoogleBuilding a developer documentation wiki, by Sarah Maddox Slide 20 20

Android  Cool look  Quick start  Introductory videos  Architectural outline  Plentiful examples  A one-stop shopBuilding a developer documentation wiki, by Sarah Maddox Slide 21 21

AndroidBuilding a developer documentation wiki, by Sarah Maddox Slide 22 22

jQuery  Parameter-determined behaviour  Contributions to the documentation  PermalinksBuilding a developer documentation wiki, by Sarah Maddox Slide 23 23

jQueryBuilding a developer documentation wiki, by Sarah Maddox Slide 24 24

Conclusion Our basic structure confirmed: Overview Quick start, including installation Tutorial Drill down to reference guidesBuilding a developer documentation wiki, by Sarah Maddox Slide 25 25 25

Conclusion Our basic structure confirmed: Overview Quick start, including installation Tutorial Drill down to reference guidesBuilding a developer documentation wiki, by Sarah Maddox Slide 26 26 26

Thinking about the big move...Wiki 1 XMLTemporary hosted site Wiki 2Building a developer documentation wiki, by Sarah Maddox Slide 27 27

Before and afterBuilding a developer documentation wiki, by Sarah Maddox Slide 28 28

BeforeBuilding a developer documentation wiki, by Sarah Maddox Slide 29 29

After Zen Foundation themeBuilding a developer documentation wiki, by Sarah Maddox Slide 30 30

After Tech writer luvBuilding a developer documentation wiki, by Sarah Maddox Slide 31 31

After Tech writer luvBuilding a developer documentation wiki, by Sarah Maddox Slide 32 32

After Navigation pluginBuilding a developer documentation wiki, by Sarah Maddox Slide 34 34

After Generated ref docsBuilding a developer documentation wiki, by Sarah Maddox Slide 35 35

After Search pluginBuilding a developer documentation wiki, by Sarah Maddox Slide 37 37

After Answers plugin Feedback pluginBuilding a developer documentation wiki, by Sarah Maddox Slide 39 39

How we got to the “after” The migration – a story in itself Customising the wiki Iterative development – ongoingBuilding a developer documentation wiki, by Sarah Maddox Slide 40 40

The story of the migrationWiki 1 XMLTemporary hosted site Wiki 2Building a developer documentation wiki, by Sarah Maddox Slide 41 41

The migration Absolute deadline Request Zen Atlas Wiki 2 ready Camp 9 26 28 May Sep SepBuilding a developer documentation wiki, by Sarah Maddox Slide 42 42

The migration Long Absolute wait deadline Request Zen Atlas Wiki 2 ready Camp 9 26 28 May Sep SepBuilding a developer documentation wiki, by Sarah Maddox Slide 43 43

The migration Long Absolute wait deadline Request Zen Atlas Wiki 2 ready Camp 9 Confluence 26 28 May Hosted Sep SepBuilding a developer documentation wiki, by Sarah Maddox Slide 44 44

Looking at the migration path againWiki 1 XMLTemporary hosted site Wiki 2Building a developer documentation wiki, by Sarah Maddox Slide 45 45

The real storyWiki 1 XMLTemporary hosted site Wiki 2Building a developer documentation wiki, by Sarah Maddox Slide 46 46

Back to the timeline... Long Absolute wait deadline Request Zen Atlas Wiki 2 ready Camp 9 Confluence 26 28 May Hosted Sep SepBuilding a developer documentation wiki, by Sarah Maddox Slide 47 47

The migration User management Long Absolute wait deadline Request Zen Atlas Wiki 2 ready Camp 9 Confluence 26 28 May Hosted Sep SepBuilding a developer documentation wiki, by Sarah Maddox Slide 48 48

The migration User management Long Planned export Absolute wait from Wiki 1 deadline Request Zen Atlas Wiki 2 ready Camp 9 Confluence 6 26 28 May Hosted Sep Sep SepBuilding a developer documentation wiki, by Sarah Maddox Slide 49 49

The migration User Upgrade Wiki 1 management to Confluence 4 Long Planned export Absolute wait from Wiki 1 deadline Request Zen Atlas Wiki 2 ready Camp 9 Confluence 1 6 26 28 May Hosted Sep Sep Sep SepBuilding a developer documentation wiki, by Sarah Maddox Slide 50 50

The migration User Upgrade Wiki 1 management to Confluence 4 Long Migrate docs Absolute wait from Wiki 1 deadline Request Zen Atlas Wiki 2 ready Camp 9 Confluence 31 1 6 26 28 May Hosted Aug Sep Sep Sep SepBuilding a developer documentation wiki, by Sarah Maddox Slide 51 51

The migration User Upgrade Wiki 1 management to Confluence 4 Long Migrate docs Absolute wait from Wiki 1 deadline Request Wiki 2 Wiki 2 Zen Atlas Wiki 2 available live ready Camp 9 Confluence 31 1 6 8 26 28 May Hosted Aug Sep Sep Sep Sep SepBuilding a developer documentation wiki, by Sarah Maddox Slide 52 52

The migration User Upgrade Wiki 1 management to Confluence 4 Long Migrate docs Absolute wait from Wiki 1 deadline Request Wiki 2 Wiki 2 Zen Atlas Wiki 2 available live ready Camp 9 Confluence 31 1 6 8 26 28 May Hosted Aug Sep Sep Sep Sep Sep Dead docs?Building a developer documentation wiki, by Sarah Maddox Slide 53 53

The migration User Upgrade Wiki 1 management to Confluence 4 Long Migrate docs Absolute wait from Wiki 1 deadline Request Wiki 2 Wiki 2 Zen Atlas Wiki 2 available live ready Camp 9 Confluence 31 1 6 8 26 28 May Hosted Aug Sep Sep Sep Sep SepBuilding a developer documentation wiki, by Sarah Maddox Slide 54 54

Broken hearts?Building a developer documentation wiki, by Sarah Maddox Slide 55 55

Broken linksBuilding a developer documentation wiki, by Sarah Maddox Slide 56 56

Moral of the storyBuilding a developer documentation wiki, by Sarah Maddox Slide 57 57

Customising the wikiBuilding a developer documentation wiki, by Sarah Maddox Slide 58 58

Customising the wiki  Zen themeBuilding a developer documentation wiki, by Sarah Maddox Slide 59 59

Customising the wiki  Zen theme  Navigation  Search  Forum panel  Feedback formBuilding a developer documentation wiki, by Sarah Maddox Slide 60 60

Customising the wiki  Zen theme  Navigation  Search  Forum panel  Feedback form  And moreBuilding a developer documentation wiki, by Sarah Maddox Slide 61 61

Customisation summaryBuilding a developer documentation wiki, by Sarah Maddox Slide 62 62

Iterative developmentBuilding a developer documentation wiki, by Sarah Maddox Slide 63 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 2Building a developer documentation wiki, by Sarah Maddox Slide 64 64

Designing the navigationBuilding a developer documentation wiki, by Sarah Maddox Slide 65 65

Designing the navigationBuilding a developer documentation wiki, by Sarah Maddox Slide 66 66

Designing the navigation – phase 1Building a developer documentation wiki, by Sarah Maddox Slide 67 67

Iterative development summaryBuilding a developer documentation wiki, by Sarah Maddox Slide 70 70

Yaayyy treesBuilding a developer documentation wiki, by Sarah Maddox Slide 71 71

Wiki and communityBuilding a developer documentation wiki, by Sarah Maddox Slide 72 72

Wiki and community Community updatesBuilding a developer documentation wiki, by Sarah Maddox Slide 73 73

Wiki and community Community updates Intellectual propertyBuilding a developer documentation wiki, by Sarah Maddox Slide 74 74

Wiki and community Community updates Intellectual property Comments and feedbackBuilding a developer documentation wiki, by Sarah Maddox Slide 75 75

Wiki and community Community updates Intellectual property Comments and feedback Doc sprintsBuilding a developer documentation wiki, by Sarah Maddox Slide 76 76

Open editing of wiki pages Is it safe? Industry and environment Authors Monitoring by technical writers RSS feeds Wiki watches You can all sleep sound tonight We’re not crazy or anythingBuilding a developer documentation wiki, by Sarah Maddox Slide 77 77

Wiki permissions and ACLA 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 allBuilding a developer documentation wiki, by Sarah Maddox Slide 78 78

Creative Commons copyright licence  CC-by licence on all pages  Use our docs in any way you like  Acknowledge us as the source  Contributors know where they stand tooBuilding a developer documentation wiki, by Sarah Maddox Slide 79 79

Comments versus forum and formBuilding a developer documentation wiki, by Sarah Maddox Slide 80 80

Doc sprints Given a focus, people do awesome stuffBuilding a developer documentation wiki, by Sarah Maddox Slide 81 81

Doc sprint results This is the doc sprint presentations, right? February 2010 23 sprinters (19 + 4) 19 tutorials, plus November 2010 30 sprinters (16 + 14) 23 user guides Yes, mate. Were going to talk about November 2011 documentation for 17 sprinters (all internal) the next two hours. Its going to be 11 tutorials awesome!Building a developer documentation wiki, by Sarah Maddox Slide 82 82

In closing  Never-ending story  Documentation as conversation  Documentation as productBuilding a developer documentation wiki, by Sarah Maddox Slide 83 83

Confluence, Tech Comm, Chocolate A wiki as platform extraordinaire for technical communication 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/Building a developer documentation wiki, by Sarah Maddox Slide 84 84

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/Building a developer documentation wiki, by Sarah Maddox Slide 85 85

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.htmlBuilding a developer documentation wiki, by Sarah Maddox Slide 86 86

Examples of good developer docsCampaign Monitor: http://www.campaignmonitor.com/apiFlickr: http://www.flickr.com/services/api/explore/?method=flickr.auth.checkTokenGoogle: http://code.google.com/apis/maps/documentation/javascript/Full list of Google APIs: http://code.google.com/more/Android: http://developer.android.com/index.htmljQuery: http://api.jquery.comRails Searchable API: http://railsapi.com/Github: http://developer.github.com/Oracles Java API docs (originally from Sun):http://download.oracle.com/javase/1.5.0/docs/api/Building a developer documentation wiki, by Sarah Maddox Slide 87 87

Building a developer documentation wiki, by Sarah Maddox Slide 88 88

https://extranet.atlassian.com	40
http://summit.stc.org	17
http://127.0.0.1	2
http://www.stc-techedit.org	1

Building a developer documentation wiki

by Sarah Maddox

Accessibility

Categories

Upload Details

Usage Rights

4 Embeds 60

Statistics

Building a developer documentation wiki Presentation Transcript