LA Netiquette. Asking the smart way - AtlasOfLivingAustralia/documentation Wiki
Table of Contents
- Before asking
- When asking
- After asking
- Possible strategies for improve our documentation with responses and shared knowledge
- Further readings
This page tries to give some basic recommendations before and after looking for help in our LA
slack channel, or using emails or mailing lists.
Service problems is a good way to understand how the LA software works and/or to learn how to tune your infrastructure, so "Keep calm and mind the bug".
Also is a good way to improve our documentation and provide future help and solutions to others, and then for having a healthful LA ecosystem.
- Try to search the
slackchannel for previous similar questions & solutions
- Try to search
githubALA repositories for some similar issue. Here you have some tip to search LA repositories easily.
- Try to search the ALA documentation
- Try our troubleshooting tips
- If you have a standard error (like a java error) try to search the internet for your error.
- If all this fails ask for help, so:
- Try to avoid direct messages in
slackor email to other LA members because we want to share knowledge, solutions, tips. Emails are very ephemeral and a "knowledge sink". In contraposition, issues or slack channel are searchable and public to others in the future.
- Try to have your personal profile updated with your organization, country, etc so it's more easy to others to understand your node situation and help
- Try to have your national node page updated in this wiki
- Try to provide enough info to facilitate others to understand your problem and to try to help you: a good description of your situation, some error logs, screenshots, URLs of your faulty service, a little of background (if your problem arises after an upgrade, or a initial installation, etc).
- Avoid non-descriptive errors like simple "Some service does not work". Using a metaphor, imagine that you fell sick and you call a doctor just saying "I'm sick". This forces your doctor to make you questions to try to understand and help you from the distance getting more info about your problem. Well with IT and LA infrastructure it's the same, others members don't have super-powers that detect what is going on in others machines & software, so please provide meaningful information of your problem.
- Did some answer solves your issue?, please give feedback, so others can find the solution in the future
- If after some time you cannot find a solution to your node problem, try to fill a issue in
githubin the relevant component repository with as much info as you can (like when asking).
- If all this fails and this issue is something important for your node, try to debug. FIXME (link to future Dev Guide).
Possible strategies for improve our documentation with responses and shared knowledge
- "Who ask, should document": If you ask, please try to document the answers or improve the wiki documentation. Many times the one that answer are quite busy to also document or don't have the same environment like the one who ask. So please try to improve this wiki.
- other option is "Who answer, first, document" or improve this documentation and answer with a link to the answer (instead of a ephemeral chat/email)
This will avoid respond again and again the same questions.