Building a developer documentation wiki

4,668 views

Published on

Or, what developers want.

Published in: Technology
2 Comments
4 Likes
Statistics
Notes
  • I am planning to document the various processes being followed around software development such as deployment procedures steps etc. So I am thinking of creating a developer documentation wiki.

    Can you please suggest some utility or the best practice which i should follow for achieving the same.
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • This is my presentation for STC Summit 2012.
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Views
Total views
4,668
On SlideShare
0
From Embeds
0
Number of Embeds
63
Actions
Shares
0
Downloads
100
Comments
2
Likes
4
Embeds 0
No embeds

No notes for slide
  • 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.
  • Building a developer documentation wiki

    1. 1. Building a developer documentation wikiBuilding a developer documentation wiki, by Sarah Maddox Slide 1 1
    2. 2. The storyWiki 1 XMLTemporary hosted site Wiki 2Building 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 communityBuilding 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 contributionsBuilding a developer documentation wiki, by Sarah Maddox Slide 4 4
    5. 5. How we found out what they wantBuilding 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  SDKsBuilding a developer documentation wiki, by Sarah Maddox Slide 7 7
    8. 8. 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
    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 ReisnerBuilding 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 guidesBuilding a developer documentation wiki, by Sarah Maddox Slide 10 10
    11. 11. 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
    12. 12. 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
    13. 13. Campaign MonitorBuilding a developer documentation wiki, by Sarah Maddox Slide 13 13
    14. 14. Campaign MonitorBuilding a developer documentation wiki, by Sarah Maddox Slide 14 14
    15. 15. Campaign MonitorBuilding a developer documentation wiki, by Sarah Maddox Slide 15 15
    16. 16. Campaign MonitorBuilding a developer documentation wiki, by Sarah Maddox Slide 16 16
    17. 17. Flickr  Real-time testing of the API  A “useful values” sectionBuilding a developer documentation wiki, by Sarah Maddox Slide 17 17
    18. 18. FlickrBuilding 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 minutesBuilding a developer documentation wiki, by Sarah Maddox Slide 19 19
    20. 20. GoogleBuilding 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 shopBuilding a developer documentation wiki, by Sarah Maddox Slide 21 21
    22. 22. AndroidBuilding a developer documentation wiki, by Sarah Maddox Slide 22 22
    23. 23. jQuery  Parameter-determined behaviour  Contributions to the documentation  PermalinksBuilding a developer documentation wiki, by Sarah Maddox Slide 23 23
    24. 24. jQueryBuilding 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 guidesBuilding 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 guidesBuilding a developer documentation wiki, by Sarah Maddox Slide 26 26 26
    27. 27. Thinking about the big move...Wiki 1 XMLTemporary hosted site Wiki 2Building a developer documentation wiki, by Sarah Maddox Slide 27 27
    28. 28. Before and afterBuilding a developer documentation wiki, by Sarah Maddox Slide 28 28
    29. 29. BeforeBuilding a developer documentation wiki, by Sarah Maddox Slide 29 29
    30. 30. After Zen Foundation themeBuilding a developer documentation wiki, by Sarah Maddox Slide 30 30
    31. 31. After Tech writer luvBuilding a developer documentation wiki, by Sarah Maddox Slide 31 31
    32. 32. After Tech writer luvBuilding a developer documentation wiki, by Sarah Maddox Slide 32 32
    33. 33. BeforeBuilding a developer documentation wiki, by Sarah Maddox Slide 33 33
    34. 34. After Navigation pluginBuilding a developer documentation wiki, by Sarah Maddox Slide 34 34
    35. 35. After Generated ref docsBuilding a developer documentation wiki, by Sarah Maddox Slide 35 35
    36. 36. BeforeBuilding a developer documentation wiki, by Sarah Maddox Slide 36 36
    37. 37. After Search pluginBuilding a developer documentation wiki, by Sarah Maddox Slide 37 37
    38. 38. BeforeBuilding a developer documentation wiki, by Sarah Maddox Slide 38 38
    39. 39. After Answers plugin Feedback pluginBuilding 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 – ongoingBuilding a developer documentation wiki, by Sarah Maddox Slide 40 40
    41. 41. The story of the migrationWiki 1 XMLTemporary hosted site Wiki 2Building 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 SepBuilding 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 SepBuilding 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 SepBuilding a developer documentation wiki, by Sarah Maddox Slide 44 44
    45. 45. Looking at the migration path againWiki 1 XMLTemporary hosted site Wiki 2Building a developer documentation wiki, by Sarah Maddox Slide 45 45
    46. 46. The real storyWiki 1 XMLTemporary hosted site Wiki 2Building 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 SepBuilding 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 SepBuilding 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 SepBuilding 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 SepBuilding 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 SepBuilding 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 SepBuilding 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 SepBuilding 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 linksBuilding a developer documentation wiki, by Sarah Maddox Slide 56 56
    57. 57. Moral of the storyBuilding a developer documentation wiki, by Sarah Maddox Slide 57 57
    58. 58. Customising the wikiBuilding a developer documentation wiki, by Sarah Maddox Slide 58 58
    59. 59. Customising the wiki  Zen themeBuilding a developer documentation wiki, by Sarah Maddox Slide 59 59
    60. 60. Customising the wiki  Zen theme  Navigation  Search  Forum panel  Feedback formBuilding a developer documentation wiki, by Sarah Maddox Slide 60 60
    61. 61. Customising the wiki  Zen theme  Navigation  Search  Forum panel  Feedback form  And moreBuilding a developer documentation wiki, by Sarah Maddox Slide 61 61
    62. 62. Customisation summaryBuilding a developer documentation wiki, by Sarah Maddox Slide 62 62
    63. 63. Iterative developmentBuilding 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 2Building a developer documentation wiki, by Sarah Maddox Slide 64 64
    65. 65. Designing the navigationBuilding a developer documentation wiki, by Sarah Maddox Slide 65 65
    66. 66. Designing the navigationBuilding a developer documentation wiki, by Sarah Maddox Slide 66 66
    67. 67. Designing the navigation – phase 1Building a developer documentation wiki, by Sarah Maddox Slide 67 67
    68. 68. Designing the navigation – phase 2Building a developer documentation wiki, by Sarah Maddox Slide 68 68
    69. 69. Designing the navigation – phase 2Building a developer documentation wiki, by Sarah Maddox Slide 69 69
    70. 70. Iterative development summaryBuilding a developer documentation wiki, by Sarah Maddox Slide 70 70
    71. 71. Yaayyy treesBuilding a developer documentation wiki, by Sarah Maddox Slide 71 71
    72. 72. Wiki and communityBuilding a developer documentation wiki, by Sarah Maddox Slide 72 72
    73. 73. Wiki and community Community updatesBuilding a developer documentation wiki, by Sarah Maddox Slide 73 73
    74. 74. Wiki and community Community updates Intellectual propertyBuilding a developer documentation wiki, by Sarah Maddox Slide 74 74
    75. 75. Wiki and community Community updates Intellectual property Comments and feedbackBuilding a developer documentation wiki, by Sarah Maddox Slide 75 75
    76. 76. Wiki and community Community updates Intellectual property Comments and feedback Doc sprintsBuilding 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 anythingBuilding 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 allBuilding 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 tooBuilding a developer documentation wiki, by Sarah Maddox Slide 79 79
    80. 80. Comments versus forum and formBuilding a developer documentation wiki, by Sarah Maddox Slide 80 80
    81. 81. Doc sprints Given a focus, people do awesome stuffBuilding 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. 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
    83. 83. In closing  Never-ending story  Documentation as conversation  Documentation as productBuilding 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.htmlBuilding a developer documentation wiki, by Sarah Maddox Slide 86 86
    87. 87. 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
    88. 88. Building a developer documentation wiki, by Sarah Maddox Slide 88 88

    ×