Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Docs as Engineering - DevRelCon London 2019

Docs as Engineering - DevRelCon London 2019

Cristiano Betta

December 10, 2019
Tweet

More Decks by Cristiano Betta

Other Decks in Technology

Transcript

  1. The Problem Hard to translate No audit trail No review

    process No modularity Hard to refactor Hard to ensure quality
  2. Docs as Code Store docs in version control Build documentation

    automatically Review all documentation Publish without user intervention There must be more?!
  3. Modularise Do one thing well Allow for easy inclusion Allow

    for easy inclusion Composition over configuration
  4. PUT /2.0/files/{id} => files__put_files_id.yml GET /2.0/folders/{id} => folders__get_folders_id.yml GET /2.0/files/{id}

    => files__get_files_id.yml DELETE /2.0/folders/{id} => folders__delete_folders_id.yml
  5. Web Hosting Netlify Functions Build Servers GitHub.com (Sources) SDK &

    CLI Docs Gatsby Source @box/developer.box.com- framework Guides, Pages, & Microcopy @box/developer.box.com Travis-ci.com Netlify CI/CD Netlify CDN OpenAPI spell check OpenAPI compilation Publishing compiled HTML/CSS/JS Pull in OpenAPI/SDK/ CLI/Microcopy data Gatsby build to HTML/ CSS/JS serving on https://box.dev Java / Python / Node / .NET Trigger validation and compilation on Git push to repo Write compiled microcopy (JSON) Write compiled OpenAPI 3.0 (JSON) Microcopy compilation Trigger rebuild of site on Git push to repo Data source Edge caching LetsEncrypt SSL “master” branch (YML) “en” branch (JSON) OpenAPI 3.0 Spec @box/box-openapi “master” branch (YML) “en” branch (JSON) Serverless function to filter GitHub web hooks to trigger the right stage to be rebuilt Trigger specific stage (production, staging, etc) to be rebuild on Netlify
  6. Web Hosting Netlify Functions Build Servers GitHub.com (Sources) SDK &

    CLI Docs Gatsby Source @box/developer.box.com- framework Guides, Pages, & Microcopy @box/developer.box.com Travis-ci.com Netlify CI/CD Netlify CDN OpenAPI spell check OpenAPI compilation Publishing compiled HTML/CSS/JS Pull in OpenAPI/SDK/ CLI/Microcopy data Gatsby build to HTML/ CSS/JS serving on https://box.dev Java / Python / Node / .NET Trigger validation and compilation on Git push to repo Write compiled microcopy (JSON) Write compiled OpenAPI 3.0 (JSON) Microcopy compilation Trigger rebuild of site on Git push to repo Data source Edge caching LetsEncrypt SSL “master” branch (YML) “en” branch (JSON) OpenAPI 3.0 Spec @box/box-openapi “master” branch (YML) “en” branch (JSON) Serverless function to filter GitHub web hooks to trigger the right stage to be rebuilt Trigger specific stage (production, staging, etc) to be rebuild on Netlify
  7. Web Hosting Netlify Functions Build Servers GitHub.com (Sources) SDK &

    CLI Docs Gatsby Source @box/developer.box.com- framework Guides, Pages, & Microcopy @box/developer.box.com Travis-ci.com Netlify CI/CD Netlify CDN OpenAPI spell check OpenAPI compilation Publishing compiled HTML/CSS/JS Pull in OpenAPI/SDK/ CLI/Microcopy data Gatsby build to HTML/ CSS/JS serving on https://box.dev Java / Python / Node / .NET Trigger validation and compilation on Git push to repo Write compiled microcopy (JSON) Write compiled OpenAPI 3.0 (JSON) Microcopy compilation Trigger rebuild of site on Git push to repo Data source Edge caching LetsEncrypt SSL “master” branch (YML) “en” branch (JSON) OpenAPI 3.0 Spec @box/box-openapi “master” branch (YML) “en” branch (JSON) Serverless function to filter GitHub web hooks to trigger the right stage to be rebuilt Trigger specific stage (production, staging, etc) to be rebuild on Netlify
  8. Web Hosting Netlify Functions Build Servers GitHub.com (Sources) SDK &

    CLI Docs Gatsby Source @box/developer.box.com- framework Guides, Pages, & Microcopy @box/developer.box.com Travis-ci.com Netlify CI/CD Netlify CDN OpenAPI spell check OpenAPI compilation Publishing compiled HTML/CSS/JS Pull in OpenAPI/SDK/ CLI/Microcopy data Gatsby build to HTML/ CSS/JS serving on https://box.dev Java / Python / Node / .NET Trigger validation and compilation on Git push to repo Write compiled microcopy (JSON) Write compiled OpenAPI 3.0 (JSON) Microcopy compilation Trigger rebuild of site on Git push to repo Data source Edge caching LetsEncrypt SSL “master” branch (YML) “en” branch (JSON) OpenAPI 3.0 Spec @box/box-openapi “master” branch (YML) “en” branch (JSON) Serverless function to filter GitHub web hooks to trigger the right stage to be rebuilt Trigger specific stage (production, staging, etc) to be rebuild on Netlify
  9. Sources Build Servers Netlify Travis In-house API Spec English Japanese

    Guides & Pages English Japanese Microcopy English Japanese Web Hosting Docs English Japanese Postman English Japanese SDKs & CLI Changelog
  10. Docs as Code Store docs in version control Build documentation

    automatically Review all documentation Publish without user intervention
  11. Docs as Code Store docs in version control Build documentation

    automatically Review all documentation Publish without user intervention Test anything that can be tested Modularise to prevent duplication Re-use to maximise value Use a pipeline to tie it all together
  12. Docs as Code Store docs in version control Build documentation

    automatically Review all documentation Publish without user intervention Test anything that can be tested Modularise to prevent duplication Re-use to maximise value Use a pipeline to tie it all together