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).

1. Make Your Contribution
Count
Adding Value to the API
as
a Technical Communicator
Petko Mikhailov
Content Strategist
PROS

2. API USERS
2
What is important about an API?
Source: ProgrammableWeb

3. API DEVELOPERS
3
The perspective matters

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. API DEVELOPERS
5
The perspective matters

6. API DEVELOPERS
6
Red state bias vs. blue state bias
The perspective matters

7. API DEVELOPERS
7
How we see 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 API user perspective
• The business perspective
Bringing in the missing perspectives
API WRITERS
The perspective matters

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. 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. 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. 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. 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. 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. 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. 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
• 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. PROCESSES MATTER
19
• The OpenAPI Specification
• Templates
• Standards and Guidelines for API Documentation
Promote standards
Standards, templates, and guidelines

20. PROCESSES MATTER
20
The OpenAPI Specification (OAS)
OAS supports collaboration

21. PROCESSES MATTER
21
Standards and Guidelines for API
Documentation
Standards benefit both writers and developers

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. PROCESSES MATTER
23
• Embed in teams and release documentation in sync
• Have your own Agile process
Make most of Agile
Agile

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. 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
• Become knowledgeable in APIs
• Become a product expert
• Expand your industry knowledge
Become a SME

27. CHOOSE YOUR PATH
27
Directions to 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 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. PUBLICITY MATTERS
30
• Showcase your work
• Announce your findings
Promote awareness
Let others know what you are doing

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. 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