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/

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