Skip to content
Astro Docs Docs (AD²)

Tips for Support Squad

If someone asks a question, answer with documentation. If the documentation doesn’t exist, write the documentation, then answer the question with documentation.

Jen Luker - @knitcodemonkey

Hello, Support Squad!

You are in a special position to contribute to Docs, with your first-hand experience helping community members with their issues. Here are some ways you can help use the knowledge gained there to improve the Docs!

User Research

Every time you interact with someone who needs help, you have an opportunity to get feedback about the quality of our documentation!

In addition to helping one person get unstuck or achieve their personal goal, you can help the entire project and community going forward if you can use a support question as an opportunity for user research.

For support that scales, and eventually becomes self-support, which reduces the support burden for everyone, it is helpful if feedback gets back to docs improvements when necessary.

Please always try to include a link to the docs when starting to help someone. It can be really tempting to answer questions yourself, or jump right in, but it is most helpful to us if you can prompt people to visit the docs:

“Hi! Yes, you will also need to install an adapter after configuring output: 'hybrid'. Here is where this is covered in the docs.” (drop a link)

Be very clear that you are not giving off RTFM vibes! You can give a short, yes/no or confirm/deny, or “ugh, sorry that’s not immediately working for you. We intend for it to work, yes!” message while dropping a docs link! You can make it clear you’d be happy to look at the issue further with them! But, we always want to figure out whether someone is here because of a failure of the docs to serve them.

No one wants to be put through a 12 minute feedback survey, or feel like they are “user research” material, but if you’re helping them then you have already established a bit of a relationship and they know you are interested in seeing their problem sovled. Please do consider (nicely! respectfully!) getting the following kinds of feeback in a support thread where/when it feels appropriate (either during, or after a resolution):

  • Did you look in the docs before asking here?
    • If yes, did you have trouble finding this section or did you find it, but it was not helpful? (e.g. poorly written, didn’t cover this situation, outdated code sample, not where you expected it to be)
    • If no, does this page have what you need(ed)? If you had seen this in docs first, would you have still needed to ask a support question? (And if so, would it have been a different question?)
  • Is there anything that docs could have provided or done differently so that you wouldn’t have needed to come ask here? (e.g. have a section / example about this; have better navigation to this location; have this page ranked higher in Algolia search results)
  • “Would you be wiling to leave feedback about this page using the Feedback widget, or would you like me to leave feedback on your behalf based on our conversation?” (Note: the feedback widget allows someone to choose leaving feedback directly in the widget OR filing a GitHub issue, so sending them there works for either situation.)

Reporting Feedback to Docs

If your support interaction reveals that docs information is incorrect, outdated, or confusing then we consider this an issue to be fixed. File a GitHub issue directly, or through the feedback widget on the docs site.

If your support interaction results in an idea for an example or recipe, then please add it to the pinned “Recipe ideas” GitHub Discussion.

For other feedback that you feel docs should have, use the feedback widget on the docs site to leave “other” feedback.

Encourage Contributions

When community members encounter Astro bugs, or have other feedback, we often do encourage them to file an Issue or submit an RFC.

If their problem could have been helped with better documentation, please encourage them to file Docs Repo Issues too!

You can point users to the Main Contributing Guide to learn about our process, about when to file an Issue vs. a PR, what kind of PRs are helpful and likely to be accepted, as well how to fork the repository and make pull requests. Even if you are not contributing to the docs, you may find it helpful to review this page so that you can help facilitate contributions from others.

In summary:

  • Generally, Issues are preferred unless for obvious typo fixes, broken links, etc. Not everything belongs in Docs, so this avoids PRs that sit while we first figure out what to do about them.
  • Issues can take the form of: the existing description was confusing; the right information was hard to find; an example like this would have been helpful, etc. Docs primarily concerns itself with its content being clear, accurate, and discoverable. Indications that we can improve on these measures are always welcome, and are most helpful if they are described with these terms in mind so we can pinpoint how best to improve.
  • Docs cannot necessarily be comprehensive. In other words, not everything is Docs material. Workarounds are helpful to individuals, but if they are not intentionally-supported features, then they are fragile and do not belong in the official documentation. Likewise, hidden “undocumented” features may be undocumented for a reason! Some of these discoveries and solutions that are questionable for docs would make great blog posts, and this would be a great way for support-seekers to contribute to the overall Astro community at large!
  • It never hurts to check existing Issues and PRs! You can avoid people making new Issues for topics that already exist. And, while not official documentation, you can still link to these Issues and PRs in order to provide helpful information! While Docs may be involved in discussing whether or not to document something, or what the best “basic” Docs example would look like, the information about the topic may still be helpful to the person in your support thread.

Provide Feedback to Docs Directly

No one is in a better position to file docs Issues than you! The same way you can encourage community members to contribute via PRs to fix small errors, Issues to alert us of ways the documentation could improve and producing one’s own content (blog posts, videos, tutorials) to share tips and tricks… all the above goes for you, too!

As a more regular, established member of the community, (and a busier one, perhaps moving quickly from one support thread to the next!) you may be more comfortable than others also connecting with Docs through:

  • The #docs channel on Discord, to alert us of something in general we should be aware of, such as “I’ve seen a lot of people having trouble with Markdown lately…”

  • pinging @team-docs in a support thread with a specific comment or question about to the existing documentation that relates to the support thread.

  • Discord events such as Docs Triage in #live-chat where you are welcome to join and provide feedback as we tackle existing Issues and PRs.