LA Netiquette. Asking the smart way - AtlasOfLivingAustralia/documentation GitHub Wiki

Table of Contents

Introduction

Welcome to our guide on seeking assistance within our Living Atlases (LA) community through Slack channels, emails, or mailing lists. Encountering service problems provides a valuable opportunity not only to deepen your understanding of the LA software but also to refine your skills in tuning your infrastructure. Remember, when facing a bug, "Keep calm and mind the bug". This is also a chance to enrich our documentation, paving the way for a more robust LA ecosystem by aiding future inquiries.

Before Asking for Help

Before reaching out for help, consider the following steps to find existing solutions:

  • Search the Slack channel for similar questions and solutions.
  • Explore GitHub ALA repositories for related issues. Here's a tip for effective searching.
  • Consult this ALA wiki documentation for guidance.
  • Review our troubleshooting tips.
  • For standard errors (e.g., Java errors), search the internet for your specific error message.

If these steps don't resolve your issue, it's time to ask for help.

While Asking for Help

To foster a culture of shared knowledge:

  • Prefer public posts in Slack or issue tracking over direct messages or emails. Emails tend to disappear into the void, while public inquiries can benefit others in the future.
  • Keep your profile up-to-date with your organization and location to help others understand your context better.
  • Provide comprehensive information to help others understand your issue: include a detailed description, error logs, screenshots, and URLs of any services experiencing issues. Background context (e.g., recent upgrades or installations) is also helpful.
  • Avoid vague descriptions like "Some service does not work". Offer detailed information to enable others to assist you effectively.

After Asking for Help

  • If you receive a solution, provide feedback to help others who may face the same issue.
  • If a solution remains elusive, consider opening a GitHub issue in the relevant repository, detailing your problem as thoroughly as possible.
  • If the issue is critical and unresolved, consider delving into debugging. Our LA Developer's Guide will offer more insights on this.

Strategies to Enhance Our Documentation

  • "Who Asks, Should Document": If you've asked a question, take the initiative to document the response or improve the wiki. Answerers are often too busy to document, and the asker is in the best position to detail the solution in the context of their environment.
  • Another approach is "Who Answers, First, Documents": Document the solution and share a link to this documentation instead of providing a transient answer via chat or email.

This strategy aims to reduce repetitive questions and enrich our collective knowledge.

Recommended Reading

For anyone seeking help or offering support, How To Ask Questions The Smart Way by Eric Steven Raymond is an invaluable resource.