Doc transformation project - Proof of Concept
-
Upload
melissa-burpo -
Category
Technology
-
view
180 -
download
0
Transcript of Doc transformation project - Proof of Concept
![Page 1: Doc transformation project - Proof of Concept](https://reader034.fdocuments.in/reader034/viewer/2022051520/58efad261a28ab466e8b4613/html5/thumbnails/1.jpg)
attribution
DOC TRANSFORMATION PROJECT: POCMelissa Burpo | @melissaburpo | telogis.com
Photo Credit: Rosa Menkman, José Vasconcelos Library
![Page 2: Doc transformation project - Proof of Concept](https://reader034.fdocuments.in/reader034/viewer/2022051520/58efad261a28ab466e8b4613/html5/thumbnails/2.jpg)
AGENDAProject walkthrough
Proof of concept demo
Discussion
Short workshop (if there’s time)
If you have a question or suggestion, jump in!
![Page 3: Doc transformation project - Proof of Concept](https://reader034.fdocuments.in/reader034/viewer/2022051520/58efad261a28ab466e8b4613/html5/thumbnails/3.jpg)
“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
![Page 4: Doc transformation project - Proof of Concept](https://reader034.fdocuments.in/reader034/viewer/2022051520/58efad261a28ab466e8b4613/html5/thumbnails/4.jpg)
WHAT’S THE PROBLEM?# of developers: ~200# of apps / services / tools: ~250
# of writers: 3
Where are the docs?
?
![Page 5: Doc transformation project - Proof of Concept](https://reader034.fdocuments.in/reader034/viewer/2022051520/58efad261a28ab466e8b4613/html5/thumbnails/5.jpg)
attribution
PROJECT GOALSFinding the docs should be easy
Writing the docs should be easy
Building the docs should be easy
![Page 6: Doc transformation project - Proof of Concept](https://reader034.fdocuments.in/reader034/viewer/2022051520/58efad261a28ab466e8b4613/html5/thumbnails/6.jpg)
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.
![Page 7: Doc transformation project - Proof of Concept](https://reader034.fdocuments.in/reader034/viewer/2022051520/58efad261a28ab466e8b4613/html5/thumbnails/7.jpg)
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
![Page 8: Doc transformation project - Proof of Concept](https://reader034.fdocuments.in/reader034/viewer/2022051520/58efad261a28ab466e8b4613/html5/thumbnails/8.jpg)
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
!!
![Page 9: Doc transformation project - Proof of Concept](https://reader034.fdocuments.in/reader034/viewer/2022051520/58efad261a28ab466e8b4613/html5/thumbnails/9.jpg)
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
![Page 10: Doc transformation project - Proof of Concept](https://reader034.fdocuments.in/reader034/viewer/2022051520/58efad261a28ab466e8b4613/html5/thumbnails/10.jpg)
DISCUSSIONAm I missing anything?
Is there another solution that
would work better?
Any questions?"
![Page 11: Doc transformation project - Proof of Concept](https://reader034.fdocuments.in/reader034/viewer/2022051520/58efad261a28ab466e8b4613/html5/thumbnails/11.jpg)
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
![Page 12: Doc transformation project - Proof of Concept](https://reader034.fdocuments.in/reader034/viewer/2022051520/58efad261a28ab466e8b4613/html5/thumbnails/12.jpg)
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)