O slideshow foi denunciado.
Utilizamos seu perfil e dados de atividades no LinkedIn para personalizar e exibir anúncios mais relevantes. Altere suas preferências de anúncios quando desejar.
Próximos SlideShares
API Technical Writing
API Technical Writing
Carregando em…3
×
1 de 88

Building a developer documentation wiki

8

Compartilhar

Baixar para ler offline

Or, what developers want.

Building a developer documentation wiki

  1. 1. Building a developer documentation wiki Building a developer documentation wiki, by Sarah Maddox Slide 1 1
  2. 2. The story Wiki 1 XML Temporary hosted site Wiki 2 Building a developer documentation wiki, by Sarah Maddox Slide 2 2
  3. 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. 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. 5. How we found out what they want Building a developer documentation wiki, by Sarah Maddox Slide 5 5
  6. 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. 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. 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. 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. 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. 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. 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. 13. Campaign Monitor Building a developer documentation wiki, by Sarah Maddox Slide 13 13
  14. 14. Campaign Monitor Building a developer documentation wiki, by Sarah Maddox Slide 14 14
  15. 15. Campaign Monitor Building a developer documentation wiki, by Sarah Maddox Slide 15 15
  16. 16. Campaign Monitor Building a developer documentation wiki, by Sarah Maddox Slide 16 16
  17. 17. Flickr  Real-time testing of the API  A “useful values” section Building a developer documentation wiki, by Sarah Maddox Slide 17 17
  18. 18. Flickr Building a developer documentation wiki, by Sarah Maddox Slide 18 18
  19. 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. 20. Google Building a developer documentation wiki, by Sarah Maddox Slide 20 20
  21. 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. 22. Android Building a developer documentation wiki, by Sarah Maddox Slide 22 22
  23. 23. jQuery  Parameter-determined behaviour  Contributions to the documentation  Permalinks Building a developer documentation wiki, by Sarah Maddox Slide 23 23
  24. 24. jQuery Building a developer documentation wiki, by Sarah Maddox Slide 24 24
  25. 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. 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. 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. 28. Before and after Building a developer documentation wiki, by Sarah Maddox Slide 28 28
  29. 29. Before Building a developer documentation wiki, by Sarah Maddox Slide 29 29
  30. 30. After Zen Foundation theme Building a developer documentation wiki, by Sarah Maddox Slide 30 30
  31. 31. After Tech writer luv Building a developer documentation wiki, by Sarah Maddox Slide 31 31
  32. 32. After Tech writer luv Building a developer documentation wiki, by Sarah Maddox Slide 32 32
  33. 33. Before Building a developer documentation wiki, by Sarah Maddox Slide 33 33
  34. 34. After Navigation plugin Building a developer documentation wiki, by Sarah Maddox Slide 34 34
  35. 35. After Generated ref docs Building a developer documentation wiki, by Sarah Maddox Slide 35 35
  36. 36. Before Building a developer documentation wiki, by Sarah Maddox Slide 36 36
  37. 37. After Search plugin Building a developer documentation wiki, by Sarah Maddox Slide 37 37
  38. 38. Before Building a developer documentation wiki, by Sarah Maddox Slide 38 38
  39. 39. After Answers plugin Feedback plugin Building a developer documentation wiki, by Sarah Maddox Slide 39 39
  40. 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. 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. 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. 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. 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. 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. 46. The real story Wiki 1 XML Temporary hosted site Wiki 2 Building a developer documentation wiki, by Sarah Maddox Slide 46 46
  47. 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. 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. 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. 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. 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. 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. 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. 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. 55. Broken hearts? Building a developer documentation wiki, by Sarah Maddox Slide 55 55
  56. 56. Broken links Building a developer documentation wiki, by Sarah Maddox Slide 56 56
  57. 57. Moral of the story Building a developer documentation wiki, by Sarah Maddox Slide 57 57
  58. 58. Customising the wiki Building a developer documentation wiki, by Sarah Maddox Slide 58 58
  59. 59. Customising the wiki  Zen theme Building a developer documentation wiki, by Sarah Maddox Slide 59 59
  60. 60. Customising the wiki  Zen theme  Navigation  Search  Forum panel  Feedback form Building a developer documentation wiki, by Sarah Maddox Slide 60 60
  61. 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. 62. Customisation summary Building a developer documentation wiki, by Sarah Maddox Slide 62 62
  63. 63. Iterative development Building a developer documentation wiki, by Sarah Maddox Slide 63 63
  64. 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. 65. Designing the navigation Building a developer documentation wiki, by Sarah Maddox Slide 65 65
  66. 66. Designing the navigation Building a developer documentation wiki, by Sarah Maddox Slide 66 66
  67. 67. Designing the navigation – phase 1 Building a developer documentation wiki, by Sarah Maddox Slide 67 67
  68. 68. Designing the navigation – phase 2 Building a developer documentation wiki, by Sarah Maddox Slide 68 68
  69. 69. Designing the navigation – phase 2 Building a developer documentation wiki, by Sarah Maddox Slide 69 69
  70. 70. Iterative development summary Building a developer documentation wiki, by Sarah Maddox Slide 70 70
  71. 71. Yaayyy trees Building a developer documentation wiki, by Sarah Maddox Slide 71 71
  72. 72. Wiki and community Building a developer documentation wiki, by Sarah Maddox Slide 72 72
  73. 73. Wiki and community Community updates Building a developer documentation wiki, by Sarah Maddox Slide 73 73
  74. 74. Wiki and community Community updates Intellectual property Building a developer documentation wiki, by Sarah Maddox Slide 74 74
  75. 75. Wiki and community Community updates Intellectual property Comments and feedback Building a developer documentation wiki, by Sarah Maddox Slide 75 75
  76. 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. 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. 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. 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. 80. Comments versus forum and form Building a developer documentation wiki, by Sarah Maddox Slide 80 80
  81. 81. Doc sprints Given a focus, people do awesome stuff Building a developer documentation wiki, by Sarah Maddox Slide 81 81
  82. 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. 83. In closing  Never-ending story  Documentation as conversation  Documentation as product Building a developer documentation wiki, by Sarah Maddox Slide 83 83
  84. 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. 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. 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. 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. 88. Building a developer documentation wiki, by Sarah Maddox Slide 88 88

Notas

  • 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.
  • ×