raml for tech writers

l All contents Copyright © 2014, MuleSoft Inc.

Spec Driven Development & Documentation

by mike stowe


• 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


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


But let me ask you…


What are the Pain Points with:•  Building APIs

•  Documenting APIs

•  Supporting APIs


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


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…


With RAML and Spec Driven Development

we can!!!

Spec Driven Development


• 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


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.


It also means bringing developers, technical writers, and even support together in the design cycle.

l All contents Copyright © 2014, MuleSoft Inc. 13

Hybrid Approach

Design Development

Continuous, fluid, changeable Static… No turns


The Agile Design Cycle


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.


And everyone knows what is going into the new API design, and knows that it has been tested to ensure usability and readability!


•  RAML

•  IO Docs

•  Swagger

•  API Blueprint

Some of Today’s Specs:


•  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:


•  You can use design patterns

•  You can reuse code (traits, resourceTypes)

More Importantly…

resourceTypes:-collection:description:Collectionofavailable<<resourcePathName>>inJukebox.get:description:Getalistof<<resourcePathName>>.responses:200:body:application/json:example:|<<exampleCollection>>


The RAML API Designer


What Does RAML Look Like?

#%RAML0.8title:WorldMusicAPIbaseUri:http://example.api.com/{version}version:v1/playlists:get:responses:200:body:application/json:example:|{“playlistID”:1,“playlistName”:“MyAwesomePlaylist”,“genre”:“top40”,“songs”:40}


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.


And because the spec is the source of truth – it can also be used for:- Documentation

- Interactive Tools

- SDK Generation

- Support

- & More!


But wait?! Does this replace technical writers???


Absolutely NOT


But it does replace “rework” and enables you to offer your users even more!


OK – enough of that. Let’s see how to actually do this stuff!


Cool huh? How about some real world examples?


“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


Get the Book

http://mulesoft.com/restbook

raml for tech writers

Internet