Upload
melissa-burpo
View
180
Download
0
Embed Size (px)
Citation preview
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)