Tips for Support Squad
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!
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-docsin 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.
If someone asks a question, answer with documentation. If the documentation doesn’t exist, write the documentation, then answer the question with documentation.