Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Make Your Contribution Count. Adding Value to the API as a Technical Communicator

18 views

Published on

Even though documenting APIs is a highly technical proposition, the contribution that a technical communicator can make to the documentation is not the same as that of the writing developer. In fact, API documentation is the place where we can shine and make the difference between failure and success of a product on the market.
In this presentation, we'll see what makes good API documentation and how API writers can bring unique value to it.
Presented at the tekom Spring Conference 2019 (Vienna).

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Make Your Contribution Count. Adding Value to the API as a Technical Communicator

  1. 1. Make Your Contribution Count Adding Value to the API as a Technical Communicator Petko Mikhailov Content Strategist PROS
  2. 2. API USERS 2 What is important about an API? Source: ProgrammableWeb
  3. 3. API DEVELOPERS 3 The perspective matters
  4. 4. API DEVELOPERS 4 • The curse 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. 5. API DEVELOPERS 5 The perspective matters
  6. 6. API DEVELOPERS 6 Red state bias vs. blue state bias The perspective matters
  7. 7. API DEVELOPERS 7 How we see the world vs. what the world is The perspective matters
  8. 8. API DEVELOPERS 8 Inside-out vs. outside-in The perspective matters
  9. 9. 9 • The API user perspective • The business perspective Bringing in the missing perspectives API WRITERS The perspective matters
  10. 10. API EXPERIENCE 10 • APIs don'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. 11. GET TECHNICAL 11 • In direction of APIs • In direction of publishing • Fix the gap between reference and non-reference content Get technical Directions to go into
  12. 12. GET TECHNICAL 12 • Static site generators • Static site generators as service • Headless content management systems • Full-circle API development portals Publishing tools Directions to go into
  13. 13. GET TECHNICAL 13 • Static site 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. 14. GET TECHNICAL 14 • Static site 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. 15. GET TECHNICAL 15 • Static site 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. 16. GET TECHNICAL 16 • Static site 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. 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. 18. PROCESSES MATTER 18 • Have engineers 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. 19. PROCESSES MATTER 19 • The OpenAPI Specification • Templates • Standards and Guidelines for API Documentation Promote standards Standards, templates, and guidelines
  20. 20. PROCESSES MATTER 20 The OpenAPI Specification (OAS) OAS supports collaboration
  21. 21. PROCESSES MATTER 21 Standards and Guidelines for API Documentation Standards benefit both writers and developers
  22. 22. PROCESSES MATTER 22 • On what 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. 23. PROCESSES MATTER 23 • Embed in teams and release documentation in sync • Have your own Agile process Make most of Agile Agile
  24. 24. PROCESSES MATTER 24 • When the 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. 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. 26. PRODUCT KNOWLEDGE MATTERS 26 • Become knowledgeable in APIs • Become a product expert • Expand your industry knowledge Become a SME
  27. 27. CHOOSE YOUR PATH 27 Directions to expand your competences in You can add value in many ways
  28. 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. 29. PUTTING IT ALL TOGETHER 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. 30. PUBLICITY MATTERS 30 • Showcase your work • Announce your findings Promote awareness Let others know what you are doing
  31. 31. SPECIALIZATION MATTERS 31 • Attend every 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. 32. SPECIALIZATION MATTERS 32 • Become a 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

×