apidays Helsinki & North 2023 - Docs-as-code at Atlassian, Szymon Ozimek, Atlassian

apidays Helsinki & North 2023
API Ecosystems - Connecting Physical and Digital
June 5 & 6, 2023

Docs-as-code at Atlassian: Jira API documentation
Szymon Ozimek, Senior Content Designer at Atlassian

------

Check out our conferences at https://www.apidays.global/

Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8

Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io

Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/

Transcript

1. Docs-as-code at Atlassian Jira API documentation SZYMON OZIMEK | SENIOR CONTENT DESIGNER | ATLASSIAN ECOSYSTEM PLATFORM
3. Agenda Introduction How we work Writing Previewing Reviewing Announcing changes Addressing issues Q&A
4. My team & org Atlassian Ecosystem Platform My company Atlassian Me Senior Content Designer Nice to meet you! This presentation API dev docs from a writer’s perspective
5. Agenda Introduction Writing Previewing Reviewing Announcing changes Addressing issues Q&A How we work
6. New code API DOC LIFECYCLE OVERVIEW Writing docs START Publication Doc reviews Announcing changes Local preview Feedback & improvements END?
7. Involved every step of the way Technical writing is often overlooked as a cost center rather than a source of value. As a craft, we’re always working to change that view. How we work Docs in DoD
8. Involved every step of the way Technical writing is often overlooked as a cost center rather than a source of value. As a craft, we’re always working to change that view. How we work Docs in DoD Dedicated craft
9. Involved every step of the way Technical writing is often overlooked as a cost center rather than a source of value. As a craft, we’re always working to change that view. How we work Docs in DoD Dedicated craft CDs in PR flow
10. Involved every step of the way Technical writing is often overlooked as a cost center rather than a source of value. As a craft, we’re always working to change that view. How we work Docs in DoD Dedicated craft CDs in PR flow Embedded or ad hoc?
11. Agenda Introduction How we work Previewing Reviewing Announcing changes Addressing issues Q&A Writing
12. How the writing gets done Same tools as engineers We use the same tools and processes for writing docs and code
13. How the writing gets done Same tools as engineers Inline editors We use the same tools and processes for writing docs and code
14. How the writing gets done Same tools as engineers Inline editors Style guide We use the same tools and processes for writing docs and code
15. How the writing gets done Same tools as engineers Inline editors Style guide Crit We use the same tools and processes for writing docs and code
16. Agenda Introduction How we work Reviewing Announcing changes Addressing issues Q&A Previewing Writing
17. Local builds & previews For all git- based doc sets Just run two commands to build & preview a doc set ./jmake build jira-rest atlas dac watch
18. Local builds & previews For all git-based doc sets Single- command build Just run two commands to build & preview a doc set ./jmake build jira-rest atlas dac watch
19. Local builds & previews For all git-based doc sets Single-command build Single-command preview Just run two commands to build & preview a doc set ./jmake build jira-rest atlas dac watch
20. Agenda Introduction How we work Previewing Announcing changes Addressing issues Q&A Reviewing Writing
21. Doc reviews = PR reviews
22. A real-life example of a code+doc PR review
23. No PR is done without docs Content designers are approvers Everyone makes mistakes Always review everything
24. Agenda Introduction How we work Previewing Reviewing Addressing issues Q&A Announcing changes Writing
25. What good are docs if no one knows they exist? ANNOUNCING CHANGES
26. You gotta flaunt it. If you build it, but they have no idea you did, they will not come. Changelogs and announcements Product changelogs
27. You gotta flaunt it. If you build it, but they have no idea you did, they will not come. Changelogs and announcements Product changelogs CDAC
28. You gotta flaunt it. If you build it, but they have no idea you did, they will not come. Changelogs and announcements Product changelogs CDAC Blogs & marketing comms
29. Agenda Introduction How we work Previewing Reviewing Announcing changes Q&A Addressing issues Writing
30. Something’ s always wrong.
31. Nothing is ever perfect We practice continuous improvement in our API docs. Feedback and continuous improvement User feedback
32. Nothing is ever perfect We practice continuous improvement in our API docs. Feedback and continuous improvement User feedback Doc backlog resolution
33. Nothing is ever perfect We practice continuous improvement in our API docs. Feedback and continuous improvement User feedback Content audits Doc backlog resolution
34. Nothing is ever perfect We practice continuous improvement in our API docs. Feedback and continuous improvement User feedback Content audits Research-based improvements Doc backlog resolution
35. New code API DOC LIFECYCLE OVERVIEW Writing docs START Publication Doc reviews Announcing changes Local preview Feedback & improvements END?
36. Agenda Introduction How we work Previewing Reviewing Announcing changes Addressing issues Q&A Writing
37. Time for Q&A
38. SZYMON OZIMEK | SENIOR CONTENT DESIGNER | ATLASSIAN ECOSYSTEM PLATFORM Thank you!