Apidays Paris 2023 - The Butterfly Effect: Transforming Legacy Documentation, Polina Zaichkina, Codat

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/

Transcript

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