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.

Building a developer documentation wiki

5.802 visualizações

Publicada em

Or, what developers want.

Publicada em: Tecnologia
  • Nice !! Download 100 % Free Ebooks, PPts, Study Notes, Novels, etc @ https://www.ThesisScientist.com
       Responder 
    Tem certeza que deseja  Sim  Não
    Insira sua mensagem aqui
  • 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.
       Responder 
    Tem certeza que deseja  Sim  Não
    Insira sua mensagem aqui
  • This is my presentation for STC Summit 2012.
       Responder 
    Tem certeza que deseja  Sim  Não
    Insira sua mensagem aqui

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

×