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/

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!