Tweet
Tweet

Slide 1

Slide 1 text

Docs as Engineering @cbetta

Slide 2

Slide 2 text

A long time ago… @cbe%a

Slide 3

Slide 3 text

Translation @cbe%a

Slide 4

Slide 4 text

developer.box.com

Slide 5

Slide 5 text

developer.box.com

Slide 6

Slide 6 text

Backup Translate Upload

Slide 7

Slide 7 text

Import & Backup Are not Symmetrical

Slide 8

Slide 8 text

Backup Translate Upload

Slide 9

Slide 9 text

10 seconds 3 months 1 month

Slide 10

Slide 10 text

That’s not all

Slide 11

Slide 11 text

The Problem @cbe%a

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

Docs as Code @cbe%a

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

@cbe%a Who am I?

Slide 17

Slide 17 text

@cbe%a Cristiano Betta Senior Developer Advocate @ Box

Slide 18

Slide 18 text

@cbe%a Cristiano Betta Developer Documenta8on Lead @ Box

Slide 19

Slide 19 text

@cbe%a Cristiano Betta Formerly @ Hoopy, PayPal

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

https://betta.io

Slide 22

Slide 22 text

@cbe%a Docs as Engineering

Slide 23

Slide 23 text

Engineering @cbe%a

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

Test & Lint @cbe%a

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

Test at source Test early

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

No content

Slide 30

Slide 30 text

Spellcheck Test the unit

Slide 31

Slide 31 text

No content

Slide 32

Slide 32 text

Validate internal links Test the whole

Slide 33

Slide 33 text

[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)

Slide 34

Slide 34 text

No content

Slide 35

Slide 35 text

Modularise @cbe%a

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

Modularise for simplification Do one thing well

Slide 38

Slide 38 text

No content

Slide 39

Slide 39 text

No content

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

No content

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

No content

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

Module composition Easy inclusion

Slide 46

Slide 46 text

No content

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

Modular UI Beyond docs

Slide 49

Slide 49 text

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

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

No content

Slide 52

Slide 52 text

Modularise Beyond docs @cbe%a

Slide 53

Slide 53 text

No content

Slide 54

Slide 54 text

No content

Slide 55

Slide 55 text

No content

Slide 56

Slide 56 text

Pipeline @cbe%a

Slide 57

Slide 57 text

Pipeline Ensure quality Maximise value Speed up delivery Encourage responsibility

Slide 58

Slide 58 text

Docs Pipeline Delivery speed

Slide 59

Slide 59 text

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

Slide 60

Slide 60 text

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

Slide 61

Slide 61 text

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

Slide 62

Slide 62 text

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

Slide 63

Slide 63 text

Beyond docs Maximise value

Slide 64

Slide 64 text

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

Slide 65

Slide 65 text

@cbe%a Where are we now?

Slide 66

Slide 66 text

No content

Slide 67

Slide 67 text

No content

Slide 68

Slide 68 text

No content

Slide 69

Slide 69 text

No content

Slide 70

Slide 70 text

No content

Slide 71

Slide 71 text

No content

Slide 72

Slide 72 text

No content

Slide 73

Slide 73 text

No content

Slide 74

Slide 74 text

No content

Slide 75

Slide 75 text

@cbe%a Recap

Slide 76

Slide 76 text

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

Slide 77

Slide 77 text

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

Slide 78

Slide 78 text

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

Slide 79

Slide 79 text

@cbe%a Thank you Cris8ano Be%a