Download to read offline
More Related Content
Similar to Make Your Contribution Count. Adding Value to the API as a Technical Communicator
Make Your Contribution Count. Adding Value to the API as a Technical Communicator
- 1. Make Your Contribution Count AddingValue to the API as a Technical Communicator Petko Mikhailov Content Strategist PROS
- 2. API USERS 2 What isimportant about an API? Source: ProgrammableWeb
- 3.
- 4. API DEVELOPERS 4 • Thecurse of knowledge is a cognitive bias that occurs when an individual, communicating with other individuals, unknowingly assumes that the others have the background to understand. What is curse of knowledge? The perspective matters
- 5.
- 6. API DEVELOPERS 6 Red statebias vs. blue state bias The perspective matters
- 7. API DEVELOPERS 7 How wesee the world vs. what the world is The perspective matters
- 8. API DEVELOPERS 8 Inside-out vs.outside-in The perspective matters
- 9. 9 • The APIuser perspective • The business perspective Bringing in the missing perspectives API WRITERS The perspective matters
- 10. API EXPERIENCE 10 • APIsdon't have UI, but there is still UX! • Part of the developer experience (DX) • Very much mixed with information experience (IX) AX – new kid on the block Acknowledge user behaviors
- 11. GET TECHNICAL 11 • Indirection of APIs • In direction of publishing • Fix the gap between reference and non-reference content Get technical Directions to go into
- 12. GET TECHNICAL 12 • Staticsite generators • Static site generators as service • Headless content management systems • Full-circle API development portals Publishing tools Directions to go into
- 13. GET TECHNICAL 13 • Staticsite generators • - Jekyll - Hugo - Spinx - MkDocs • Static site generators as service • Headless content management systems • Full-circle API development portals Publishing tools Directions to go into
- 14. GET TECHNICAL 14 • Staticsite generators • Static site generators as service • - GitHub Pages • - CloudCannon • - Read the Docs • Headless content management systems • Full-circle API development portals Publishing tools Directions to go into
- 15. GET TECHNICAL 15 • Staticsite generators • Static site generators as service • Headless content management systems • - Forestry.io • - Netlify CMS • - Readme.io • Full-circle API development portals Publishing tools Directions to go into
- 16. GET TECHNICAL 16 • Staticsite generators • Static site generators as service • Headless content management systems • Full-circle API development portals • - SwaggerHub • - Stoplight • - APIgator Publishing tools Directions to go into
- 17. GET INTO MARKETING 17 •Keep it technical • No hype • Adhere to the “how-to” format • Write blog posts Marketing technical writing Directions to go into
- 18. PROCESSES MATTER 18 • Haveengineers properly write reference documentation - empower them to write • - docs-as-code • - templates and standards • Facilitate reviews • - Make documentation part of the release - Make the process formal • Get user feedback and re-route it to engineering teams Encourage devs’ participation Establish processes
- 19. PROCESSES MATTER 19 • TheOpenAPI Specification • Templates • Standards and Guidelines for API Documentation Promote standards Standards, templates, and guidelines
- 20. PROCESSES MATTER 20 The OpenAPISpecification (OAS) OAS supports collaboration
- 21. PROCESSES MATTER 21 Standards andGuidelines for API Documentation Standards benefit both writers and developers
- 22. PROCESSES MATTER 22 • Onwhat to focus on the first draft • Expand the reviewers’ circle: • - Product Manager • - Field Engineers • - Support Iterate Use draft iterations for better quality and engagement
- 23. PROCESSES MATTER 23 • Embedin teams and release documentation in sync • Have your own Agile process Make most of Agile Agile
- 24. PROCESSES MATTER 24 • Whenthe code is likely to change • When there aren’t enough resources to maintain that documentation • When the code is simple enough Know what and when not to document Keep the docs current
- 25. GO INTO TESTING 25 •Collaborate with testers • Test everything you document • Test the parameters • Check the error messages Add value through testing Testing is as important for the docs as it is for the API
- 26. PRODUCT KNOWLEDGE MATTERS 26 • Becomeknowledgeable in APIs • Become a product expert • Expand your industry knowledge Become a SME
- 27. CHOOSE YOUR PATH 27 Directionsto expand your competences in You can add value in many ways
- 28. GET IN DEPTH 28 •Workflow and process maps across the content • Visual diagrams to assist with key concepts • Glossaries and alignment with industry standard terminology • Topics consistency across the entire dev portal • Distillation of information into high-level summaries and quick reference guides • Conducting surveys and feedback about the user experience • Alignment of the API usage descriptions with the user story Documentation-specific things to focus on Bring value through your core competences
- 29. PUTTING IT ALLTOGETHER 29 • Assess what is lacking/missing • Compare against competition • Consider the feedback • - from API users • - from your own use • - from research • What resources are available? • What will make the biggest impact? • Cost/effort vs. effect • What of your contributions will be most visible? • What do you need to go there? Define your API documentation goals Your game plan
- 30. PUBLICITY MATTERS 30 • Showcaseyour work • Announce your findings Promote awareness Let others know what you are doing
- 31. SPECIALIZATION MATTERS 31 • Attendevery project meeting • Logs bugs • Provide input on design and the feature roadmap • Maintain the documentation roadmap • Keep the documentation dept backlog • Keep pace with the sprints • Be fully immersed and engaged with the team Here is what it takes Keep your efforts focused
- 32. SPECIALIZATION MATTERS 32 • Becomea SME • Build test apps • Push tasks through the whole process, from end to end. • Work closely with engineers • You profile and interact with the users • Participate in usability testing • Immerse into the industry tech • Keep up with both internal and external news related to the product Here is what it takes Keep your efforts focused