Riley Siebel & Mark Winberry - Case Study: Creating a DocOps/Docs-As-Code DevPortal for C3.ai

"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)

Problem space

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.

Goal

• 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

Realization

1. Customizations for C3.ai

   • Conceptual Docs:
     • Topics
     • Guides & How-To’s
     • c3typ Reference Docs (thousands!)
   • C3 Integrations
     • Okta SSO
     • Discourse Community Forums
   • Solr Search for site & forums
   • Custom HTML → PDF Generator
   • Custom Javascript In-page search for c3types
   • Custom Exporter - Importer
      

2. 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:
     • Reconstruct links
     • Build the composite Guides and How-To’s from multiple C3 Markdown files
   • Versioning support to prevent duplicate content
   • Inserted into Developer Portal
      

3. 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
      

4. Learnings

   • 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