Docs as Engineering - DevRelCon London 2019

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/
30. Spellcheck Test the unit
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)
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
40. 176 API endpoints > 80 response and request objects 19,000+ lines of OpenAPI 3.0
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
44. 1 file per API endpoint 1 file per response resource Compilation using Travis CI
45. Module composition Easy inclusion
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
52. Modularise Beyond docs @cbe%a
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?
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