attribution

DOC TRANSFORMATION PROJECT: POCMelissa Burpo | @melissaburpo | telogis.com

Photo Credit: Rosa Menkman, José Vasconcelos Library

AGENDAProject walkthrough

Proof of concept demo

Discussion

Short workshop (if there’s time)

If you have a question or suggestion, jump in!

“Make it easier for developers to self-maintain documentation, especially for our internal tools. You can’t do everything.

- The request from my boss that started this whole project

WHAT’S THE PROBLEM?# of developers: ~200# of apps / services / tools: ~250

# of writers: 3

Where are the docs?

?

attribution

PROJECT GOALSFinding the docs should be easy

Writing the docs should be easy

Building the docs should be easy

RESEARCH: DEV ENVIRONMENTLANGUAGES

Version control:

Mercurial and Kiln

Continuous Integration:

TeamCity

Preference for RAML over Swagger

Little interest in supporting

API consoles for internal tools

C#,

JavaScript,

Python,

Ruby

others

API MODELING LANGUAGE CORE TOOLS

Takeaways: I need a language-agnostic doc tool with good command line support and being able to do something with RAML specs would be nice too.

CHOOSING TOOLS 1 What’s the best way to manage the content?

2 Which markup language should we use?

3 Which static site generator should we use?

4 What should we do with the RAML specs?

static site generator_

markdown_

mkdocs*_

raml2md_

* check out staticgen.com

attribution

DEMO

View the site

Walkthrough of files in a sample project (VaaH REST API)

Markdown, RAML (+ includes), YAML

Preview site locally while writing docs: mkdocs serve

Build a site: mkdocs build —clean

Build Markdown file from given RAML spec (in POC folder structure): node raml2md-master/lib/raml2md.js -i raml/vaah.raml -o docs/vaah.md

!!

NEXT STEPSImprove RAML to Markdown template

Create custom mkdocs theme

Centralize assets

Automate doc builds

Make it easy to add docs to a new project

Make it easy to find the docs

Photo Credit: postscapes, ulleungdo island stairs

DISCUSSIONAm I missing anything?

Is there another solution that

would work better?

Any questions?"

attribution

WORKSHOP SETUP

For mkdocs, install:

Python (2.6, 2.7, 3.3, 3.4 or 3.5)

Pip (comes installed with Python 3.4+ and 2.7.9+)

mkdocs: pip install mkdocs

For the POC version of raml2md, install:

Node

Download master branch of user herophuong’s forked version of raml2md: https://github.com/herophuong/raml2md

Unzip raml2md, install project dependencies: npm install

##Note: The raml2md steps are only required for the POC

attribution

MKDOCS INTRO

From a command line, cd to your preferred test directory

Create a new project:mkdocs new wtd-project

Open the folder to inspect the files in the new project

Serve the docs locally:mkdocs serve

Open http://127.0.0.1:8000/ in your browser to view the site

Use a text editor to edit one of the Markdown files, then check the page in your browser

Edit the mkdocs.yml config file and change the site name:site_name: My awesome new WTD project

Build the docs: mkdocs build

(basic steps shamelessly stolen from mkdocs.org)