Developer documentation by now includes both reference and conceptual information.
Developer experience when onboarding newcomers and time-to-first-API-call is crucial.
Who is your audience? For example, external docs are the prime source of truth for your internal audience too.
Steps to improve your docs through feedback:
- Identify your internal audience. Who is using your docs?
- Solicit internal feedback. What is missing?
- Collect external feedback. Give a way to contribute.
- Apply feedback to your docs. Implement effectively.
- Who is your internal audience?
- Developers creating tools utilizing your APIs
- Customer support, Product support engineers, Solution architects
- Those talking about your APIs to an external audience: Marketing, Sales / Sales engineering, Product managers, etc.
- How do you know who uses your docs?
- Those contacting your team regularly or asking for docs on certain topics
- Change requests on docs - directly requesting or tagging that which will affect docs
- On go-to-market / release meetings: who invites you, who talks about docs
- Who else should be aware of the status of docs?
- Developer relations team
- Learning development / Training
- Those who use / discuss the APIs regularly
- Create communication channels for questions, update requests, initial discussions - a place for others to chime in on ongoing processes.
- Create docs JIRA projects / labels: tag what will have an effect on docs, tickets for changes.
- Regular meetings with key stakeholders: what content needs to be included with upcoming changes, to meld with the overall DX. Align & link dev docs with upcoming marketing, devrel, blog content.
- Keep all information in one place to track quantity and quality. Not all feedback is equal, assess the need and possible contribution to the documentation.
Collecting external feedback
- Can't ask everyone: no direct contact, too many people.
- Establish audience personas (background, tools, behaviors, goals, frustrations). Not only developers! Get insights from developer advocates, support agents.
- One collecting place for all feedback.
- Create predictable habits, patterns on reaching out. For example, GitHub issue links from docs, or a form embedded for direct feedback.
- Assess if feedback is helpful and sufficiently broad use case? Set questions to create actionable answers.
- Many outside sources: all established online community presences are good for candid feedback but require a lot of involvement and resources. Developer advocates, community managers can help to catch such feedback.
- Convert every feedback into the same format.
Some typical feedback
- Insights from internal audiences:
- Incomplete (more context could be added) or not up-to-date information
- Suggestions on best practices / troubleshooting
- From external audiences:
- Not enough information about specific concepts
- Certain information can’t be found
- Popular use cases to cover
- Mostly the internal and external feedback can be both applied, they do not interfere.
- Consider quality and quantity to decide what feedback to act on.
- Consider an internal-only documentation set with more in-depth information. Keep track of the decision-making in case of switching over later.
- In doubt? Always benefit the external user.
- Track metrics on effect of implementing feedback (Less support calls on a topic? Increased use?)
- Alert external audience on changes: change log, social media or blog post, even email updates.
- Tell your internal audience on having acted on their feedback and on changes made.
- Create separate specific channels for your internal- and external audience.