Docs as Engineering - DevRelCon London 2019

Docs as Engineering - DevRelCon London 2019

E0ee803f10db4d5fb85f8288a421850b?s=128

Cristiano Betta

December 10, 2019
Tweet

Transcript

  1. Docs as Engineering @cbetta

  2. A long time ago… @cbe%a

  3. Translation @cbe%a

  4. developer.box.com

  5. developer.box.com

  6. Backup Translate Upload

  7. Import & Backup Are not Symmetrical

  8. Backup Translate Upload

  9. 10 seconds 3 months 1 month

  10. That’s not all

  11. The Problem @cbe%a

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

    process No modularity Hard to refactor Hard to ensure quality
  13. Docs as Code @cbe%a

  14. https://www.writethedocs.org/guide/docs-as-code/

  15. Docs as Code Store docs in version control Build documentation

    automatically Review all documentation Publish without user intervention There must be more?!
  16. @cbe%a Who am I?

  17. @cbe%a Cristiano Betta Senior Developer Advocate @ Box

  18. @cbe%a Cristiano Betta Developer Documenta8on Lead @ Box

  19. @cbe%a Cristiano Betta Formerly @ Hoopy, PayPal

  20. @cbe%a Cristiano Betta Writes @ be%a.io

  21. https://betta.io

  22. @cbe%a Docs as Engineering

  23. Engineering @cbe%a

  24. Software engineering Modularity KISS DRY Anticipate Change Do one thing

    well Many more… Test early
  25. Test & Lint @cbe%a

  26. Testing & Linting Test early Test often Test the parts

    Test the whole
  27. Test at source Test early

  28. https://stoplight.io/open-source/spectral/

  29. None
  30. Spellcheck Test the unit

  31. None
  32. Validate internal links Test the whole

  33. [Upload a file](../../../files/upload) [Upload a file](guide://file/upload) https://developer.box.com/en/guides/files/upload https://developer.box.com/jp/guides/files/upload [File](resource://file) [Upload

    a file](endpoint://post_files_content)
  34. None
  35. Modularise @cbe%a

  36. Modularise Do one thing well Allow for easy inclusion Allow

    for easy inclusion Composition over configuration
  37. Modularise for simplification Do one thing well

  38. None
  39. None
  40. 176 API endpoints > 80 response and request objects 19,000+

    lines of OpenAPI 3.0
  41. None
  42. 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
  43. None
  44. 1 file per API endpoint 1 file per response resource

    Compilation using Travis CI
  45. Module composition Easy inclusion

  46. None
  47. source/attributes/file_id.yml source/paths/files__get_files_id.yml

  48. Modular UI Beyond docs

  49. source/guides/api-calls/pagination/marker-based.md developer.box.com/en/guides/api-calls/pagination/marker-based

  50. github.com/box/box-windows-sdk-v2/blob/master/docs/files.md

  51. None
  52. Modularise Beyond docs @cbe%a

  53. None
  54. None
  55. None
  56. Pipeline @cbe%a

  57. Pipeline Ensure quality Maximise value Speed up delivery Encourage responsibility

  58. Docs Pipeline Delivery speed

  59. 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
  60. 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
  61. 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
  62. 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
  63. Beyond docs Maximise value

  64. 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
  65. @cbe%a Where are we now?

  66. None
  67. None
  68. None
  69. None
  70. None
  71. None
  72. None
  73. None
  74. None
  75. @cbe%a Recap

  76. Docs as Code Store docs in version control Build documentation

    automatically Review all documentation Publish without user intervention
  77. 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
  78. 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
  79. @cbe%a Thank you Cris8ano Be%a