Scott Morrison
Autodesk
A Unified Documentation Pipeline for an Internal and External Docs
About the Talk
Our unified documentation pipeline allows our team to write and publish docs internally to our Backstage-based internal portal. When ready to be made public, the docs can be quickly redeployed to our custom-built external developer portal.
Documentation is typically written and used internally before an API is released publicly. At Autodesk we have an internal developer portal, powered by the Backstage framework and an external portal which is custom built. They both support the same documentation format and input types. It supports documentation in Markdown, RST, OpenAPI 2 and 3, GraphQL schemas, JavaScript SDKs and TypeScript SDKs all using the “docs as code” approach. During development, the docs are initially published to our internal portal, and used by internal developers. When the API is ready to be published, we can easily redeploy the same documentation to our external developer portal, with the same content and look & feel. We also support running the doc pipeline locally, without pushing to GitHub, to allow local preview of the docs. This lets our developers and writers work in a more WYSIWYG style. I will demonstrate an early version of that running on my laptop. We simplified CI/CD support of our documentation pipeline by creating a custom GitHub app that handles all the details of invoking the pipeline when changes are made to our docs. Developers just need to create a simple documentation configuration file and attach the app to the repository in order to start publishing.
About the Speaker
Scott is a distinguished software architect in the Developer Enablement group at Autodesk. He has been a developer and architect at Autodesk for 30 years. His current responsibilities include the Autodesk Platform Services Developer Portal, the internal Developer Portal, the Autodesk REST API Standard and the Autodesk Platform Services SDK team.
