Building a developer documentation wiki
•Download as PPTX, PDF•
8 likes•5,904 views
Or, what developers want.
Recommended
More Related Content
Viewers also liked
Viewers also liked (20)
Similar to Building a developer documentation wiki
Similar to Building a developer documentation wiki (20)
More from Sarah Maddox
More from Sarah Maddox (13)
Recently uploaded
Recently uploaded (20)
Building a developer documentation wiki
- 1. Building a developer documentation wiki Building a developer documentation wiki, by Sarah Maddox Slide 1 1
- 2. The story Wiki 1 XML Temporary hosted site Wiki 2 Building a developer documentation wiki, by Sarah Maddox Slide 2 2
- 3. Let’s talk about What developers want Before and after How we got to the “after” Wiki and community Building a developer documentation wiki, by Sarah Maddox Slide 3 3
- 4. What developers want Single, dedicated site Clear navigation Simple start tutorials reference Relevant search Comments and contributions Building a developer documentation wiki, by Sarah Maddox Slide 4 4
- 5. How we found out what they want Building a developer documentation wiki, by Sarah Maddox Slide 5 5
- 6. 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
- 7. 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 SDKs Building a developer documentation wiki, by Sarah Maddox Slide 7 7
- 8. 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?” Building a developer documentation wiki, by Sarah Maddox Slide 8 8
- 9. 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 Reisner Building a developer documentation wiki, by Sarah Maddox Slide 9 9
- 10. Conclusion A good structure for developer documentation Overview Quick start, including installation Tutorial(s) Drill down to reference guides Building a developer documentation wiki, by Sarah Maddox Slide 10 10
- 11. If we don't get the documentation right they will hate us no matter what else we give them Building a developer documentation wiki, by Sarah Maddox Slide 11 11
- 12. Examples of respected documentation sites Campaign Monitor See the references section at the end Flickr of the slide deck Google Android jQuery More Building a developer documentation wiki, by Sarah Maddox Slide 12 12
- 13. Campaign Monitor Building a developer documentation wiki, by Sarah Maddox Slide 13 13
- 14. Campaign Monitor Building a developer documentation wiki, by Sarah Maddox Slide 14 14
- 15. Campaign Monitor Building a developer documentation wiki, by Sarah Maddox Slide 15 15
- 16. Campaign Monitor Building a developer documentation wiki, by Sarah Maddox Slide 16 16
- 17. Flickr Real-time testing of the API A “useful values” section Building a developer documentation wiki, by Sarah Maddox Slide 17 17
- 18. Flickr Building a developer documentation wiki, by Sarah Maddox Slide 18 18
- 19. Google Overview of what’s possible Standard code format Good look “Hello world” < 30 minutes Building a developer documentation wiki, by Sarah Maddox Slide 19 19
- 20. Google Building a developer documentation wiki, by Sarah Maddox Slide 20 20
- 21. Android Cool look Quick start Introductory videos Architectural outline Plentiful examples A one-stop shop Building a developer documentation wiki, by Sarah Maddox Slide 21 21
- 22. Android Building a developer documentation wiki, by Sarah Maddox Slide 22 22
- 23. jQuery Parameter-determined behaviour Contributions to the documentation Permalinks Building a developer documentation wiki, by Sarah Maddox Slide 23 23
- 24. jQuery Building a developer documentation wiki, by Sarah Maddox Slide 24 24
- 25. Conclusion Our basic structure confirmed: Overview Quick start, including installation Tutorial Drill down to reference guides Building a developer documentation wiki, by Sarah Maddox Slide 25 25 25
- 26. Conclusion Our basic structure confirmed: Overview Quick start, including installation Tutorial Drill down to reference guides Building a developer documentation wiki, by Sarah Maddox Slide 26 26 26
- 27. Thinking about the big move... Wiki 1 XML Temporary hosted site Wiki 2 Building a developer documentation wiki, by Sarah Maddox Slide 27 27
- 28. Before and after Building a developer documentation wiki, by Sarah Maddox Slide 28 28
- 29. Before Building a developer documentation wiki, by Sarah Maddox Slide 29 29
- 30. After Zen Foundation theme Building a developer documentation wiki, by Sarah Maddox Slide 30 30
- 31. After Tech writer luv Building a developer documentation wiki, by Sarah Maddox Slide 31 31
- 32. After Tech writer luv Building a developer documentation wiki, by Sarah Maddox Slide 32 32
- 33. Before Building a developer documentation wiki, by Sarah Maddox Slide 33 33
- 34. After Navigation plugin Building a developer documentation wiki, by Sarah Maddox Slide 34 34
- 35. After Generated ref docs Building a developer documentation wiki, by Sarah Maddox Slide 35 35
- 36. Before Building a developer documentation wiki, by Sarah Maddox Slide 36 36
- 37. After Search plugin Building a developer documentation wiki, by Sarah Maddox Slide 37 37
- 38. Before Building a developer documentation wiki, by Sarah Maddox Slide 38 38
- 39. After Answers plugin Feedback plugin Building a developer documentation wiki, by Sarah Maddox Slide 39 39
- 40. How we got to the “after” The migration – a story in itself Customising the wiki Iterative development – ongoing Building a developer documentation wiki, by Sarah Maddox Slide 40 40
- 41. The story of the migration Wiki 1 XML Temporary hosted site Wiki 2 Building a developer documentation wiki, by Sarah Maddox Slide 41 41
- 42. The migration Absolute deadline Request Zen Atlas Wiki 2 ready Camp 9 26 28 May Sep Sep Building a developer documentation wiki, by Sarah Maddox Slide 42 42
- 43. The migration Long Absolute wait deadline Request Zen Atlas Wiki 2 ready Camp 9 26 28 May Sep Sep Building a developer documentation wiki, by Sarah Maddox Slide 43 43
- 44. The migration Long Absolute wait deadline Request Zen Atlas Wiki 2 ready Camp 9 Confluence 26 28 May Hosted Sep Sep Building a developer documentation wiki, by Sarah Maddox Slide 44 44
- 45. Looking at the migration path again Wiki 1 XML Temporary hosted site Wiki 2 Building a developer documentation wiki, by Sarah Maddox Slide 45 45
- 46. The real story Wiki 1 XML Temporary hosted site Wiki 2 Building a developer documentation wiki, by Sarah Maddox Slide 46 46
- 47. Back to the timeline... Long Absolute wait deadline Request Zen Atlas Wiki 2 ready Camp 9 Confluence 26 28 May Hosted Sep Sep Building a developer documentation wiki, by Sarah Maddox Slide 47 47
- 48. The migration User management Long Absolute wait deadline Request Zen Atlas Wiki 2 ready Camp 9 Confluence 26 28 May Hosted Sep Sep Building a developer documentation wiki, by Sarah Maddox Slide 48 48
- 49. 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 Sep Building a developer documentation wiki, by Sarah Maddox Slide 49 49
- 50. 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 Sep Building a developer documentation wiki, by Sarah Maddox Slide 50 50
- 51. 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 Sep Building a developer documentation wiki, by Sarah Maddox Slide 51 51
- 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 Building a developer documentation wiki, by Sarah Maddox Slide 52 52
- 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 Sep Dead docs? Building a developer documentation wiki, by Sarah Maddox Slide 53 53
- 54. 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 Building a developer documentation wiki, by Sarah Maddox Slide 54 54
- 55. Broken hearts? Building a developer documentation wiki, by Sarah Maddox Slide 55 55
- 56. Broken links Building a developer documentation wiki, by Sarah Maddox Slide 56 56
- 57. Moral of the story Building a developer documentation wiki, by Sarah Maddox Slide 57 57
- 58. Customising the wiki Building a developer documentation wiki, by Sarah Maddox Slide 58 58
- 59. Customising the wiki Zen theme Building a developer documentation wiki, by Sarah Maddox Slide 59 59
- 60. Customising the wiki Zen theme Navigation Search Forum panel Feedback form Building a developer documentation wiki, by Sarah Maddox Slide 60 60
- 61. Customising the wiki Zen theme Navigation Search Forum panel Feedback form And more Building a developer documentation wiki, by Sarah Maddox Slide 61 61
- 62. Customisation summary Building a developer documentation wiki, by Sarah Maddox Slide 62 62
- 63. Iterative development Building a developer documentation wiki, by Sarah Maddox Slide 63 63
- 64. 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 Building a developer documentation wiki, by Sarah Maddox Slide 64 64
- 65. Designing the navigation Building a developer documentation wiki, by Sarah Maddox Slide 65 65
- 66. Designing the navigation Building a developer documentation wiki, by Sarah Maddox Slide 66 66
- 67. Designing the navigation – phase 1 Building a developer documentation wiki, by Sarah Maddox Slide 67 67
- 68. Designing the navigation – phase 2 Building a developer documentation wiki, by Sarah Maddox Slide 68 68
- 69. Designing the navigation – phase 2 Building a developer documentation wiki, by Sarah Maddox Slide 69 69
- 70. Iterative development summary Building a developer documentation wiki, by Sarah Maddox Slide 70 70
- 71. Yaayyy trees Building a developer documentation wiki, by Sarah Maddox Slide 71 71
- 72. Wiki and community Building a developer documentation wiki, by Sarah Maddox Slide 72 72
- 73. Wiki and community Community updates Building a developer documentation wiki, by Sarah Maddox Slide 73 73
- 74. Wiki and community Community updates Intellectual property Building a developer documentation wiki, by Sarah Maddox Slide 74 74
- 75. Wiki and community Community updates Intellectual property Comments and feedback Building a developer documentation wiki, by Sarah Maddox Slide 75 75
- 76. Wiki and community Community updates Intellectual property Comments and feedback Doc sprints Building a developer documentation wiki, by Sarah Maddox Slide 76 76
- 77. 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 anything Building a developer documentation wiki, by Sarah Maddox Slide 77 77
- 78. 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 all Building a developer documentation wiki, by Sarah Maddox Slide 78 78
- 79. 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 too Building a developer documentation wiki, by Sarah Maddox Slide 79 79
- 80. Comments versus forum and form Building a developer documentation wiki, by Sarah Maddox Slide 80 80
- 81. Doc sprints Given a focus, people do awesome stuff Building a developer documentation wiki, by Sarah Maddox Slide 81 81
- 82. 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. We're going to talk about November 2011 documentation for 17 sprinters (all internal) the next two hours. It's going to be 11 tutorials awesome! Building a developer documentation wiki, by Sarah Maddox Slide 82 82
- 83. In closing Never-ending story Documentation as conversation Documentation as product Building a developer documentation wiki, by Sarah Maddox Slide 83 83
- 84. 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
- 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/ Building a developer documentation wiki, by Sarah Maddox Slide 85 85
- 86. 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 Building a developer documentation wiki, by Sarah Maddox Slide 86 86
- 87. 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, by Sarah Maddox Slide 87 87
- 88. Building a developer documentation wiki, by Sarah Maddox Slide 88 88
Editor's Notes
- Speaker’s notes:Hallo everyone. I’m Sarah Maddox, a technical writer at Atlassian. Let’s talk about building a developer documentation wiki.First, a bit of background. Our company develops and sells a number of software products, largely web applications.Each application is extensible. This means that developers can build plugins and add-ons for the application, to add extra functionality or customise the look and feel.To make the applications extensible, we provide APIs (application programming interfaces), plugin frameworks, SDKs and other development tools.The developer documentation shows people how to use those tools. The audience consists of both internal developers (our own staff) and a large community of external developers who make a living by extending our products.
- Speaker’s notes:This presentation will cover these topics:What developers want, and how we found that out.A look at the documentation before and after the move.How we got to the “after”.Wiki and community – what works and what doesn’t.
- Speaker’s notes:I also trawled through a number of online forums and blogs.These are the sources I found most valuable. The full titles and links are in the references section at the end of the slide deck. I’ll post my slides on SlideShare and on my ffeathers blog after the conference.Stack Overflow is a question-and-answer site for developers. There are many discussions about developer documentation on the site. I’ve given you the link to one of them.Pamela Fox has posted a Flickr set showing the landing pages for various APIs, libraries and languages. It’s interesting to flick through them, comparing them, and also gaining an overall impression of what’s out there.The Programmable Web hosted a guest post by Peter Gruenbaum.Jacob Kaplan-Moss’s article is part of a series called “Writing great documentation”.Alex Reisner proposes a standard format for documentation of open source projects.
- Speaker’s notes:Summarising the information from those sources, I think that this is a good structure for developer documentation:An overview, telling you what you can do with the development kit, APIs, and other tools.A quick start guide. This should include instructions on installing the development kit or any other doodads needed.A tutorial that gets a “hello world” program up and running in a short time. More tutorials to illustrate the key features of the developer offering.Detailed reference documentation.
- Speaker’s notes:Daniel Franz is the product manager for developer relations in our company. This is what he said during the design phase of the project:“If we don’t get the documentation right they will hate us, no matter what else we give them.Speaking from the heart as a technical writer: It’s great to have such enthusiastic support from the product manager.
- Speaker’s notes:Let’s look at some examples of respected documentation sites gathered during our research, and what my supergeeks said about them.
- Speaker’s notes:Campaign Monitor kicks off with a good welcome page. It tells you what you can do, and links you up with everything you need.http://www.campaignmonitor.com/api
- Speaker’s notes:Taking a closer look at the welcome page.I love the message it gives to developers – we will help you build awesomeness.
- Speaker’s notes:The getting started page feeds you digestible chunks of information, nicely wrapped in cool green text and friendly words.The message is:“We’re going to make things easy for you.”
- Speaker’s notes:The reference documents follow the pattern of clarity and cleanness set by the introduction.This page is about the account API. It starts with a summary of what the API does.Then it shows you how to do specific things, such as getting a list of all clients in your account.http://www.campaignmonitor.com/api/account/
- Speaker’s notes:Many people recommended the Flickr documentation. One of my supergeeks said: “Being able to test the API in real time is awesome.”He was also impressed with the “useful values” section on the right.http://www.flickr.com/services/api/explore/?method=flickr.auth.checkToken
- Speaker’s notes:A closer look at the Flickr page.
- Speaker’s notes:Google comes up often too.What’s good about the Google guides:You can easily see what is possible.They have a standard format for their code samples.The pages look good. I have a sneaking suspicion that this is more important in a developer’s estimation than we may at first think.It is very easy to get started. You can have a working “hello world” in less than 30 minutes. http://code.google.com/apis/maps/documentation/javascript/Here’s the full list of Google APIs:http://code.google.com/more/
- Speaker’s notes:A closer look at the Google page.
- Speaker’s notes:What’s good about these guides:The page looks very cool. (Yes, that again.)The guide gets you started quickly.The introductory videos help in getting you started.There’s a useful outline of the overall architecture.There are plenty of examples.The documentation site provides a one-stop shop for everything related to development. http://developer.android.com/index.html
- Speaker’s notes:A closer look at the Android page.Android is just plain cool.
- Speaker’s notes:jQuery is for front-end geeks.What’s good about these guides:The documentation successfully deals with an interesting challenge: The language supports functions that vary in behaviour based on their parameters. In this example, the attr() function supports two different calling modes. Documentation supports contributions.Good permalinks. You can bookmark a link into the reference documentation, and share it with other people. http://api.jquery.com/attr/Here’s the full list of jQuery APIs:http://api.jquery.com/
- Speaker’s notes:A closer look at the jQuery page.
- Speaker’s notes:...Let’s take a quick look at the documentation as it was before the big move, and what it looked like afterwards.
- Speaker’s notes:Let’s talk about the migration from Wiki 1 to Wiki 2.The migration is a story in itself.Then we’ll see how we customised the wiki, and discuss the fact that development is iterative and ongoing.
- Speaker’s notes: Iterative developmentOur process has been rapid and iterative throughout, in the design of the user interface as well as the content. This process is ongoing, even now.
- Speaker’s notes:The process:Analyse the requirement.Mock up a solution and brainstorm the mockup with the product manager.Develop the solution on the test site.Use the solution and get the team to give feedback on it.Put it onto the live site.Get feedback from users.Update it in response to feedback.Let’s walk through one example: The design of the navigation panel.
- Speaker’s notes: Yaayyy treesWe are still changing the navigation. Our focus has moved onto the content of the tree, rather than its visual design. At the moment, we are receiving feedback that the tree has too many levels. It is too deep, and people have trouble finding the information they want.I see this as vindication of the standpoint that people do need and appreciate a navigation tool as well as the search!BTW, this is a real tree. I took the picture myself. To me, it looks like a person in a tall hat, dancing.
- Speaker’s notes: Comments versus links to forum and formIn the “before and after”, I showed that we removed the ability to comment on the pages, and now have a feedback form and a link to the forum instead.Our experiences – the forum:The forum works very well. It serves the readers well.The feed from the forum into the documentation does not work so well. We don’t yet have a good match between content in the forum discussions and content on the pages.Forum users and our readers say that the tagging system on the forum is not detailed enough to let them classify the information to the level needed. The vagueness of tagging also makes it difficult to match forum posts to documentation pages. We need to do more thinking here.It’s a pity we have lost the vibrancy of comments on the pages. The documentation is less interactive, and has lost the benefit of having corrections and additions posted by readers.Our experiences – the feedback form:The volume of feedback is too high for us to manage.Readers feel that their feedback goes into a big black hole, because they cannot see the results, and other people cannot respond when the technical writers are overloaded.