Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

of

DocOps Engineering Great Docs Slide 1 DocOps Engineering Great Docs Slide 2 DocOps Engineering Great Docs Slide 3 DocOps Engineering Great Docs Slide 4 DocOps Engineering Great Docs Slide 5 DocOps Engineering Great Docs Slide 6 DocOps Engineering Great Docs Slide 7 DocOps Engineering Great Docs Slide 8 DocOps Engineering Great Docs Slide 9 DocOps Engineering Great Docs Slide 10 DocOps Engineering Great Docs Slide 11 DocOps Engineering Great Docs Slide 12 DocOps Engineering Great Docs Slide 13 DocOps Engineering Great Docs Slide 14 DocOps Engineering Great Docs Slide 15 DocOps Engineering Great Docs Slide 16 DocOps Engineering Great Docs Slide 17 DocOps Engineering Great Docs Slide 18 DocOps Engineering Great Docs Slide 19 DocOps Engineering Great Docs Slide 20 DocOps Engineering Great Docs Slide 21 DocOps Engineering Great Docs Slide 22 DocOps Engineering Great Docs Slide 23 DocOps Engineering Great Docs Slide 24 DocOps Engineering Great Docs Slide 25 DocOps Engineering Great Docs Slide 26 DocOps Engineering Great Docs Slide 27 DocOps Engineering Great Docs Slide 28 DocOps Engineering Great Docs Slide 29 DocOps Engineering Great Docs Slide 30 DocOps Engineering Great Docs Slide 31 DocOps Engineering Great Docs Slide 32 DocOps Engineering Great Docs Slide 33 DocOps Engineering Great Docs Slide 34 DocOps Engineering Great Docs Slide 35 DocOps Engineering Great Docs Slide 36 DocOps Engineering Great Docs Slide 37 DocOps Engineering Great Docs Slide 38 DocOps Engineering Great Docs Slide 39 DocOps Engineering Great Docs Slide 40 DocOps Engineering Great Docs Slide 41 DocOps Engineering Great Docs Slide 42 DocOps Engineering Great Docs Slide 43 DocOps Engineering Great Docs Slide 44 DocOps Engineering Great Docs Slide 45 DocOps Engineering Great Docs Slide 46 DocOps Engineering Great Docs Slide 47 DocOps Engineering Great Docs Slide 48 DocOps Engineering Great Docs Slide 49 DocOps Engineering Great Docs Slide 50 DocOps Engineering Great Docs Slide 51 DocOps Engineering Great Docs Slide 52 DocOps Engineering Great Docs Slide 53 DocOps Engineering Great Docs Slide 54 DocOps Engineering Great Docs Slide 55 DocOps Engineering Great Docs Slide 56 DocOps Engineering Great Docs Slide 57 DocOps Engineering Great Docs Slide 58 DocOps Engineering Great Docs Slide 59 DocOps Engineering Great Docs Slide 60 DocOps Engineering Great Docs Slide 61 DocOps Engineering Great Docs Slide 62 DocOps Engineering Great Docs Slide 63 DocOps Engineering Great Docs Slide 64 DocOps Engineering Great Docs Slide 65 DocOps Engineering Great Docs Slide 66
Upcoming SlideShare
What to Upload to SlideShare
Next
Download to read offline and view in fullscreen.

3 Likes

Share

Download to read offline

DocOps Engineering Great Docs

Download to read offline

Great documentation is hard to build, maintain and continually improve on. Developers have exceptionally high expectations when it comes to documentation and will often judge a product on how articulately it communicates how to use the product as much as the actual offerings of the platform or tool itself.

You may have the best product on the market, maybe even the most competitively priced, but if nobody understands how to actually use it then its failure is almost certainly inevitable. Poor documentation often stems from lack of deep insight, the kind of insight where one understands the quirks and edge cases that if not addressed can lead to confusion and a lost customer. It’s important to put documentation into the hands of the people who understand the product the best, to enable people and to allow those who have faced challenges to put it right for the next person.

This talk is about the open-source platform and tools that I built when developing Nexmo Developer and how it has enabled us to build a powerful and flexible platform for writing rich documentation collaboratively with ease. I’ll cover our goals and how we met them, the challenges we faced during development and our tooling including our custom Markdown pipeline, Open API Specification generated API Reference Pages and the various components we use throughout our documentation.

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all

DocOps Engineering Great Docs

  1. 1. ENGINEERING DOCS API THE DOCS AMSTERDAM 4TH DECEMBER 2017 LABFOO@ great
  2. 2. WHAT IS @jaredmorgs - WTD PODCAST #4
  3. 3. AARON - SAM - AMANDA - ALEX - BIBI - LEGGETTER - OLIA - MICHAEL - CHRIS - MARK - ERIC DEVREL TEAM @LABFOO TECHNICAL LEAD @TOMMORRIS TECHNICAL WRITER +
  4. 4. TECHNICAL WRITER PRODUCT OWNER ENGINEERS
  5. 5. ⚠ ❌ TECHNICAL WRITER PRODUCT OWNERS
  6. 6. THINK LIKE AN ENGINEER
  7. 7. TECHNICAL WRITER PRODUCT OWNER ENGINEER CUSTOMERS SUPPORT YOU?
  8. 8. { }… Open Source Tooling Contribution Guides Docs like CodeAutomation
  9. 9. OPEN SOURCE
  10. 10. 1,567 changes 22 Contributors 70 COMMITS 3rd December 2017 - Non-core team contributors
  11. 11. POWERFUL TOOLS + +
  12. 12. +
  13. 13. +
  14. 14. YES
  15. 15. #$%&' INTERNATIONALISATION
  16. 16. DATABASE AUTHENTICATION SESSION USER INPUT WORKERS
  17. 17. + + TOOLSINTUITIVE
  18. 18. _documentation sms overview.md guides encoding.md custom-sender-id.md building-blocks send-an-sms.md receiving-an-sms.md verify voice
  19. 19. MARKDOWN
  20. 20. EASY READABLE POPULAR POWERFUL (
  21. 21. EASY READABLE POPULAR POWERFUL (
  22. 22. extending-markdown.md
  23. 23. PIPELINE
  24. 24. MD html 1 2 3 4 5 10 9 8 7 6 15 14 13 12 11 17 18 19 20 21 16 22
  25. 25. FILTER #1 FRONTMATTER overview.md frontmatter_filter.rb
  26. 26. FILTER #1 FRONTMATTER overview.md frontmatter_filter.rb
  27. 27. FILTER #1 FRONTMATTER overview.md frontmatter_filter.rb
  28. 28. FILTER #17 TOOLTIPS styleguide.md tooltip_filter.rb
  29. 29. FILTER #17 TOOLTIPS styleguide.md tooltip_filter.rb
  30. 30. FILTER #9 TABBED CONTENT overview.md codefence YAML plugin name alpha.md bravo.md charlie.md tabbed_content_filter.rb
  31. 31. FILTER #9 TABBED CONTENT overview.md alpha.md bravo.md charlie.md tabbed_content_filter.rb
  32. 32. FILTER #9 TABBED CONTENT overview.md alpha.md bravo.md charlie.md tabbed_content_filter.rb
  33. 33. FILTER #9 TABBED CONTENT overview.md alpha.md bravo.md charlie.md tabbed_content_filter.rb
  34. 34. PLUGIN EXTENDED IMPLICIT
  35. 35. IMPLICIT Heading External Link + PHPInliner, Frontmatter h1#i-am-a-h1
  36. 36. EXTENDED Collapsible Content JS Sequence Diagrams Labels + Escaping, Tooltip, Modals, Columns, Manual Anchors
  37. 37. PLUGINS Scripted Screenshots Tabbed Examples + Tabbed Content, Partials External Code
  38. 38. Best 9ms Worst 360ms Average 40ms 0 5 10 15 20 5 20 35 50 65 80 95 110 125 140 155 170 185 200 215 230 245 260 275 290 305 320 335
  39. 39. CONTRIBUTION
 GUIDES
  40. 40. BUILDING MAINTAINING easyIS IS
  41. 41. AUTOMATION
  42. 42. Screenshots Code Examples Link Testing Spelling & Grammar?
  43. 43. rake diff:build:base rake repos:pull rake diff:build:compare
  44. 44. rake diff:build:compare
  45. 45. DOCS LIKE CODE { }…
  46. 46. Git & GitHub Documenting REST CI / Automation Reviews
  47. 47. { }… Open Source Tooling Contribution Guides Docs like CodeAutomation
  48. 48. TECHNICAL WRITERfind out more at https://developer.nexmo.com/team WE ARE hiring
  49. 49. ENGINEERING DOCS API THE DOCS AMSTERDAM 4TH DECEMBER 2017 LABFOO@ great
  • marcospinello

    Mar. 19, 2018
  • AlexeyAkimov2

    Dec. 19, 2017
  • KennethLau21

    Dec. 12, 2017

Great documentation is hard to build, maintain and continually improve on. Developers have exceptionally high expectations when it comes to documentation and will often judge a product on how articulately it communicates how to use the product as much as the actual offerings of the platform or tool itself. You may have the best product on the market, maybe even the most competitively priced, but if nobody understands how to actually use it then its failure is almost certainly inevitable. Poor documentation often stems from lack of deep insight, the kind of insight where one understands the quirks and edge cases that if not addressed can lead to confusion and a lost customer. It’s important to put documentation into the hands of the people who understand the product the best, to enable people and to allow those who have faced challenges to put it right for the next person. This talk is about the open-source platform and tools that I built when developing Nexmo Developer and how it has enabled us to build a powerful and flexible platform for writing rich documentation collaboratively with ease. I’ll cover our goals and how we met them, the challenges we faced during development and our tooling including our custom Markdown pipeline, Open API Specification generated API Reference Pages and the various components we use throughout our documentation.

Views

Total views

2,619

On Slideshare

0

From embeds

0

Number of embeds

2,159

Actions

Downloads

6

Shares

0

Comments

0

Likes

3

×