Apidays Paris 2023 - Software and APIs for Smart, Sustainable and Sovereign Societies December 6, 7 & 8, 2023 The Butterfly Effect: Transforming Legacy Documentation Polina Zaichkina, Senior Technical Writer at Codat ------ 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. T
ransforming Legacy Documentation
The Butterfly Effect:
apidays Paris | Dec 2023

2. Who
Polina Zaichkina
Senior technical writer
producing and editing
public documentation,
supporting OAS
maintenance, enabling
internal collaboration
T R A N S F O R M I N G L E G A C Y D O C U M E N TAT I O N
Where
Codat
Products for companies
like banks, payment
providers, and more, to
connect to the software
small businesses use
What
Docs migration
Challenges with legacy
documentation
Changes to process,
tooling, team, content
Lessons learned
Key results and benefits

3. C O D AT ' S L E G A C Y D O C U M E N TAT I O N

4. 🦋Transforming legacy documentation
Challenges
•
•
•
•
•
•
Desired architecture was not achievable
Richer content was not supported
No review and approval workflow
Limited collaboration due to license availability
Cost implications
No opportunity for improvement

5. C O D AT ' S U P D AT E D D O C U M E N TAT I O N

6. 🦋Transforming legacy documentation
Challenges
•
•
•
•
•
•
Desired architecture was not achievable
Richer content was not supported
No review and approval workflow
Limited collaboration due to license availability
Cost implications
No opportunity for improvement
•
•
•
•
•
•
Flexibility in build and styling
Benefits of the docs-as-code approach
PR workflow enables others to contribute
Minimal upskilling for contributors
Anyone can produce content
Build previews to experience docs as the reader
Our solution

7. Challenges
T
ooling
Content
Process
T
eam
🦋Transforming legacy documentation
B U T T E R F LY E F F E C T O F T R A N S F O R M AT I O N

8. 🦋Transforming legacy documentation
•
•
•
Be clear on your why
Communicate the challenges
T
ake the plunge
Lessons learned
C H A L L E N G E S
•
•
•
•
•
•
Understand what exactly are the issues with your
current documentation
Examine your as-is and to-be state
Explain the challenges with the existing solution
Get buy-in and support to use resources
Y
ou can do a big migration
It will only get more complicated later

9. 🦋Transforming legacy documentation
•
•
•
Leverage skills in your team
Research and experiment
Prepare to be annoyed
Lessons learned
T O O L I N G
•
•
•
•
•
•
•
Explore the skills and interests of colleagues
T
echnical barriers may be lower than you think
Available skills and challenges determine the solution
Research the technical tooling available and trial it
Changing tools is often not a seamless experience
Be prepared for unsupported syntax and broken links
See how you can make the migration easier

10. 🦋Transforming legacy documentation
•
•
•
Ask others for help
Share the responsibility
Collaborate and enable
Lessons learned
P R O C E S S
•
•
•
•
•
Process changes might lag - start early if you can
Documentation is part of the product and is a shared
responsibility
T
ech writers support others - get others to support
tech writers
Y
our new tools can support a change in process
Provide content and architectural guidance to others

11. 🦋Transforming legacy documentation
•
•
•
Audit your docs
Iterate and experiment
Documentation freeze
Lessons learned
C O N T E N T
•
•
•
•
•
•
•
Review your content, structure, types as a whole
Record feedback, ideas, snags, improvements
Arrange and communicate a documentation freeze
Avoid changes that might become irrelevant
Be ready for double maintenance
Play around with the content in the new tool
New tools may open new horizons

12. 🦋Transforming legacy documentation
•
•
•
Documentation is not just
writing
Embrace stewardship
Expect upskilling
Lessons learned
T E A M
•
•
•
•
T
ech writers are decision-makers, editors, enablers,
tutors, and creatives
New tooling means developing new skills
Decide if upskilling is right for your team
More time is spent on value add and enrichment

13. 🦋Transforming legacy documentation
•
•
•
•
•
•
T
eam tech content is steering the ship
Shared responsibility increases collaboration
Cost-saving opportunities
Documentation is viewed as important
Content is richer and more accurate
Experiments are possible, and ongoing work does not
interrupt existing user experience
N OW N E X T
•
•
•
•
Continue to improve legacy content
Enhance documentation to be more developer-
oriented
Increase the variety of content types
Add custom functionality to the pages

14. Thank you
Senior technical writer
Polina Zaichkina