~sircmpwn/sr.ht-dev

sr.ht-docs: Add IRC etiquette document v1 SUPERSEDED

Oliver Leaver-Smith: 1
 Add IRC etiquette document

 2 files changed, 92 insertions(+), 0 deletions(-)
Thanks for the feedback, I have sent a v2 patch
Export patchset (mbox)
How do I use this?

Copy & paste the following snippet into your terminal to import this patchset into git:

curl -s https://lists.sr.ht/~sircmpwn/sr.ht-dev/patches/26983/mbox | git am -3
Learn more about email & git

[PATCH sr.ht-docs] Add IRC etiquette document Export this patch

---
 chat.sr.ht/etiquette.md | 91 +++++++++++++++++++++++++++++++++++++++++
 chat.sr.ht/index.md     |  1 +
 2 files changed, 92 insertions(+)
 create mode 100644 chat.sr.ht/etiquette.md

diff --git a/chat.sr.ht/etiquette.md b/chat.sr.ht/etiquette.md
new file mode 100644
index 0000000..3c3ed1e
--- /dev/null
+++ b/chat.sr.ht/etiquette.md
@@ -0,0 +1,91 @@
# IRC Etiquette

IRC is a wonderful place. It has the power to connect people from all over the planet who share a common goal or interest. IRC has grown very organically over the many years it has been around, and each network operates differently. This guide exists to give an introduction to general IRC etiquette and ideals specific to [chat.sr.ht](https://chat.sr.ht).

## Don't ask to ask

Just ask! It's not uncommon to see a message in IRC such as

```
user: who here knows go?
```

What this looks like to others users is

```
user: who here knows go and is willing to commit to
      looking at a problem they have no details of
      and might not even be related to go?
```

A better way to ask this question is along the lines of

```
user: I'm trying to do [thing] in go but I'm getting
      the error [error], I've tried [workaround] but
      this doesn't resolve the error. Does anyone
      have any suggestions please?
```

## Be precise

Sending a message like "This app doesn't build" is unhelpful to you and those who you want assistance from. Even those willing to help will need to ask so many follow up questions that it's barely worth their time. You should include the following information as part of your original request to make it easier to help you:

* What are you trying to do?
* What has happened instead?
* What is your setup?
* What did you try already?
* Are there any logs or errors?
* Has it ever worked?

e.g.

```
user: I am trying to build "foo" but it is failing. I'm
      using OpenBSD and the error says "use of undeclared
      identifier 'bar'". I have that read I might need to
      change where the the compiler is looking for libs to
      include but I am not 100% sure how to do this in the
      Makefile
```

## Answer questions

If someone is assisting you and asks a question, it's in your bests interests to answer as this is likely relevant to a fix. Likewise, if you change something unprompted and this either changes or fixes the problem, let those who are helping you know.

## Don't be demanding

Nobody owes you anything. The people helping are doing so out of the kindness of their own heart. As such, don't expect an individual to personally guide you through a lengthy troubleshooting process from start to finish.

## Read the docs

You should read the docs to find a solution to your problem before approaching IRC. If you are asked to read the docs then you should do so. Often the docs for a project are linked in a channel's topic.

If you don't understand something in the docs then of course you can ask questions around it, for example

```
user: I've read the docs on Python tuples, but I don't
      understand why I would use one over a list?
```

## Don't `/msg` people without asking

Discussing a problem in an open forum is not an invitation to message a user directly. For one thing, the rest of the channel will miss out on any learnings that come from the interaction and troubleshooting. If you are going to message someone, you should ask them first if it's OK to do so.

## Don't be offended

You might get the impression that people on IRC are rude. This is generally not the case, and you are simply being given a direct answer to your question such as "reload the service" or "read httpd.conf(5)". You question has likely been answered a few times already today and people simply want to answer your question, rather than become your friend.

## Stick around

Sometimes you are lucky and have your questions answered straight away. Other times you may have to wait 30 minutes or so for an answer (or longer in quieter channels). Be patient and don't leave after a couple of minutes because an expert may be about to respond.

As you pick up knowledge, please consider staying in that channel to assist other users with their questions. You probably understand more than you think, and so can become a vital resource for the community by simply being a part of it.

## Share your solution

If you figure out the solution to your problem outside of the channel, or one of the suggestions given to you works, please feed that back to the channel so that everyone involved can learn from it. Even if it was something you think is stupid, you won't look stupid for sharing the answer.

## Use a pastebin

When sharing logs, config files or errors, sometimes they are on more than one line. You shouldn't send multiple lines in IRC, instead using a pastebin service such as [paste.st.ht](https://paste.sr.ht). Do not blindly paste a URL to your snippet though, you must provide some context for it in the channel.
diff --git a/chat.sr.ht/index.md b/chat.sr.ht/index.md
index 31c307f..03f644c 100644
--- a/chat.sr.ht/index.md
+++ b/chat.sr.ht/index.md
@@ -31,6 +31,7 @@ We have a few additional guides for different audiences:
- [Setting up an IRC channel for your project](/chat.sr.ht/channels.md)
- [Writing an IRC bot](/chat.sr.ht/bots.md)
- [Information for network operators](/chat.sr.ht/ircops.md)
- [Etiquette for new IRC users](/chat.sr.ht/etiquette.md)

## chat.sr.ht software

-- 
2.24.3 (Apple Git-128)
I think it'll would be nice to wrap this document into 72 columns as
well. It's a good etiquette and it matches other sr.ht-docs pages.