"The thing that I'd like to take through the whole thread of this presentation is that even with extremely complicated software, with literally hundreds of thousands of APIs, you can still follow good docs-as-code practices and build a system that delivers the outcome you're looking for, no matter how complex your software is." (Riley Siebel)
"I think part of the keys to our success that I hope people will take away is that you don't let the complexity of your own system scare you away from trying to deliver a better developer experience and implement something that will make everyone's life better, like a good DocOps process with docs-as-code. And just the importance of good teamwork." (Mark Winberry)
C3.ai built their own unified type-system that allows interaction with multitudes of systems and types of users through one platform. They needed a developer portal to host documentation that was sourced from a very complex documentation set:
Some of the documentation existed as markdown docs of various flavors.
Guides were composites of several markdown docs.
The majority of the reference documentation is generated from the code. Thousands of reference docs generated for various versions of the platform.
An application's documentation is the union of the documentation of all the dependencies.
Any customer can change (remix) a type to their needs.
Evaluation and update of application is only possible by already having paid access.
Provide convenient access to docs sourced from code
Support evaluation of the product through documentation
Appropriate UX for developer site for C3.ai
Augment other developer experiences: training & community
Customizations for C3.ai
Guides & How-To’s
c3typ Reference Docs (thousands!)
Discourse Community Forums
Solr Search for site & forums
Custom HTML → PDF Generator
Custom Exporter - Importer
Docs as Code Exporter/Importer
Go application, Docker container
Runs in the C3 CI/CD build & test pipeline
Makes api calls to a transient C3 Server and C3 code repo
Retrieves an JSON object
Store the data in a temporary, non-persistent database
After Export, content is then processed to:
Build the composite Guides and How-To’s from multiple C3 Markdown files
Versioning support to prevent duplicate content
Inserted into Developer Portal
What worked well: Keys to Success
Onsite Workshop - Face to face
Very clear priorities, with guiding principles and vision
Iterative Design & Demos
Clear Approval process: Designs & Implementation Google Sheet
Shared Communications: Figma, Slack, Google Docs
Recorded calls & demos
You cannot over-communicate
Leave lots of time for design & iterations: embrace change
Didn’t write a test interface for the C3 API→
A bug-fix that happened upstream at C3 broke functionality in the site
Silent Failure → bad
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.