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.

RAML for Tech Writers

2,062 views

Published on

RAML isn't just for developers - learn how RAML can help the whole team by getting everyone on the same page, and letting developers, technical writers, and support work together to create an even better API - while also taking advantage of all the tools the RAML open source community has to offer - letting you create better, faster, and even add interactivity to your docs!

Published in: Internet

RAML for Tech Writers

  1. 1. l All contents Copyright © 2014, MuleSoft Inc. Spec Driven Development & Documentation by mike stowe
  2. 2. l All contents Copyright © 2014, MuleSoft Inc. • API Fanatic • Open Source Contributor • Author, Speaker, Consultant • 10+ years hacking Professional Code • Dev Relations Manager at MuleSoft About Me Follow me on Twitter: @mikegstowe
  3. 3. l All contents Copyright © 2014, MuleSoft Inc. More importantly, I’ve been responsible for creating, documenting, and supporting APIs. And I can tell you – all of these are TOUGH! About Me Follow me on Twitter: @mikegstowe
  4. 4. l All contents Copyright © 2014, MuleSoft Inc. But let me ask you…
  5. 5. l All contents Copyright © 2014, MuleSoft Inc. What are the Pain Points with: •  Building APIs •  Documenting APIs •  Supporting APIs
  6. 6. l All contents Copyright © 2014, MuleSoft Inc. My #1 Problems: •  APIs are not designed for the users •  Doc Teams get left out of the loop •  No such thing as easy to debug code
  7. 7. l All contents Copyright © 2014, MuleSoft Inc. My #1 Problems: •  APIs are not designed for the users •  Doc Teams get left out of the loop •  No such thing as easy to debug code
  8. 8. l All contents Copyright © 2014, MuleSoft Inc. We could simplify the process, and make it more efficient for everyone? What if we could actually do even more… with less work? But What If…
  9. 9. l All contents Copyright © 2014, MuleSoft Inc. With RAML and Spec Driven Development we can!!! Spec Driven Development
  10. 10. l All contents Copyright © 2014, MuleSoft Inc. • Define your API before Coding • Use Design Patterns/ Code Reuse • Mock and get User Feedback • Make Necessary Changes • Start Coding – to the Spec • DO NOT DEVIATE! Use Spec Driven Development
  11. 11. l All contents Copyright © 2014, MuleSoft Inc. Spec Driven Development means a hybrid between agile and contract methodologies. You should develop your spec iteratively, incorporating agile user testing. However, the actual development (coding) of your API should be static, driven by the spec with no deviation.
  12. 12. l All contents Copyright © 2014, MuleSoft Inc. It also means bringing developers, technical writers, and even support together in the design cycle.
  13. 13. l All contents Copyright © 2014, MuleSoft Inc.13 Hybrid Approach Design Development Continuous, fluid, changeable Static… No turns
  14. 14. l All contents Copyright © 2014, MuleSoft Inc.14 The Agile Design Cycle
  15. 15. l All contents Copyright © 2014, MuleSoft Inc. The goal is that by utilizing agile user testing, carefully designing, and prototyping your API in an iterative state, that most design related issues have already been discovered and resolved. Allowing you to develop fearlessly.
  16. 16. l All contents Copyright © 2014, MuleSoft Inc. And everyone knows what is going into the new API design, and knows that it has been tested to ensure usability and readability!
  17. 17. l All contents Copyright © 2014, MuleSoft Inc.17 •  RAML •  IO Docs •  Swagger •  API Blueprint Some of Today’s Specs:
  18. 18. l All contents Copyright © 2014, MuleSoft Inc.18 •  You can define your API in just a few lines of code •  You can see what it would look like as you go •  You can quickly prototype it for devs to try •  You can quickly make tweaks/ changes •  You can easily document your API •  You can let developers try your API online •  You can let developers interact with your and other APIs •  Generate SDKs/ client libraries for your API (APIMatic.io) Using RAML You Can:
  19. 19. l All contents Copyright © 2014, MuleSoft Inc.19 •  You can use design patterns •  You can reuse code (traits, resourceTypes) More Importantly… resourceTypes: - collection: description: Collection of available <<resourcePathName>> in Jukebox. get: description: Get a list of <<resourcePathName>>. responses: 200: body: application/json: example: | <<exampleCollection>>
  20. 20. l All contents Copyright © 2014, MuleSoft Inc.20 The RAML API Designer
  21. 21. l All contents Copyright © 2014, MuleSoft Inc.21 What Does RAML Look Like? #%RAML 0.8 title: World Music API baseUri: http://example.api.com/{version} version: v1 /playlists: get: responses: 200: body: application/json: example: | { “playlistID” : 1, “playlistName” : “My Awesome Playlist”, “genre” : “top40”, “songs” : 40 }
  22. 22. l All contents Copyright © 2014, MuleSoft Inc. Remember, your spec is not a one-and-done, rather it is the blueprint for your API. Anytime you do something to your API you should be modifying the spec and going through user testing before writing code. You should never have code that does something not defined by your spec.
  23. 23. l All contents Copyright © 2014, MuleSoft Inc. And because the spec is the source of truth – it can also be used for: - Documentation - Interactive Tools - SDK Generation - Support - & More!
  24. 24. l All contents Copyright © 2014, MuleSoft Inc. But wait?! Does this replace technical writers???
  25. 25. l All contents Copyright © 2014, MuleSoft Inc. Absolutely NOT
  26. 26. l All contents Copyright © 2014, MuleSoft Inc. But it does replace “rework” and enables you to offer your users even more!
  27. 27. l All contents Copyright © 2014, MuleSoft Inc. OK – enough of that. Let’s see how to actually do this stuff!
  28. 28. l All contents Copyright © 2014, MuleSoft Inc. Cool huh? How about some real world examples?
  29. 29. l All contents Copyright © 2014, MuleSoft Inc. “I’ve never come across all this in my previous TechWriter life, but noticed very soon that our inhouse documentation tool compared with simply editing markdown and raml files enriches my knowledge and makes my work far easier.” -Birgit, e.Pages Dev Blog
  30. 30. l All contents Copyright © 2014, MuleSoft Inc. Get the Book http://mulesoft.com/restbook

×