Docs as Engineering - DevRelCon London 2019

Transcript

1. Docs as
   Engineering
   @cbetta
   

   View Slide

2. A long time ago…
   @cbe%a
   

   View Slide

3. Translation
   @cbe%a
   

   View Slide

4. developer.box.com
   

   View Slide

5. developer.box.com
   

   View Slide

6. Backup
   Translate
   Upload
   

   View Slide

7. Import &
   Backup
   Are not
   Symmetrical
   

   View Slide

8. Backup
   Translate
   Upload
   

   View Slide

9. 10 seconds
   3 months
   1 month
   

   View Slide

10. That’s not all
    

    View Slide

11. The Problem
    @cbe%a
    

    View Slide

12. The Problem
    Hard to translate
    No audit trail
    No review process
    No modularity
    Hard to refactor
    Hard to ensure quality
    

    View Slide

13. Docs as Code
    @cbe%a
    

    View Slide

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

    View Slide

15. Docs as Code
    Store docs in version control
    Build documentation automatically
    Review all documentation
    Publish without user intervention
    There must be more?!
    

    View Slide

16. @cbe%a
    Who am I?
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

21. https://betta.io
    

    View Slide

22. @cbe%a
    Docs as Engineering
    

    View Slide

23. Engineering
    @cbe%a
    

    View Slide

24. Software engineering
    Modularity
    KISS
    DRY
    Anticipate Change
    Do one thing well
    Many more…
    Test early
    

    View Slide

25. Test & Lint
    @cbe%a
    

    View Slide

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

    View Slide

27. Test at source
    Test early
    

    View Slide

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

    View Slide

29. View Slide

30. Spellcheck
    Test the unit
    

    View Slide

31. View Slide

32. Validate internal links
    Test the whole
    

    View Slide

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)
    

    View Slide

34. View Slide

35. Modularise
    @cbe%a
    

    View Slide

36. Modularise
    Do one thing well
    Allow for easy inclusion
    Allow for easy inclusion
    Composition over configuration
    

    View Slide

37. Modularise for
    simplification
    Do one thing well
    

    View Slide

38. View Slide

39. View Slide

40. 176 API endpoints
    > 80 response and request objects
    19,000+ lines of OpenAPI 3.0
    

    View Slide

41. View Slide

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
    

    View Slide

43. View Slide

44. 1 file per API endpoint
    1 file per response resource
    Compilation using Travis CI
    

    View Slide

45. Module composition
    Easy inclusion
    

    View Slide

46. View Slide

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

    View Slide

48. Modular UI
    Beyond docs
    

    View Slide

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

    View Slide

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

    View Slide

51. View Slide

52. Modularise
    Beyond docs
    @cbe%a
    

    View Slide

53. View Slide

54. View Slide

55. View Slide

56. Pipeline
    @cbe%a
    

    View Slide

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

    View Slide

58. Docs Pipeline
    Delivery speed
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

63. Beyond docs
    Maximise value
    

    View Slide

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
    

    View Slide

65. @cbe%a
    Where are we now?
    

    View Slide

66. View Slide

67. View Slide

68. View Slide

69. View Slide

70. View Slide

71. View Slide

72. View Slide

73. View Slide

74. View Slide

75. @cbe%a
    Recap
    

    View Slide

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

    View Slide

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
    

    View Slide

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
    

    View Slide

79. @cbe%a
    Thank you
    Cris8ano Be%a
    

    View Slide