$30 off During Our Annual Pro Sale. View Details »

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. 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