Communication guide

One of the big problems of large communities is keeping communication effective. The challenge is to keep providing everyone with high quality, compact information.

This often becomes difficult when many people participate in a discussion, as the amount of text and time spent in writing grows more quickly than the amount of information that is actually produced.

It is important to keep focused on improving our body of knowledge, just like we keep improving our body of software: working online, messages keep living after their recipient has read them, and become public pieces of information that can show in the forums, Github issues, go into the repos get indexed in search engines, linked by other people, quoted or pasted in an HOWTO or an FAQ and so on.

Improving means caring for the information to have quality content and to be communicated efficiently. It also means making the process of producing and improving of our body of knowledge pleasant and sustainable over time.

What follows is a collection of suggestions about these three aspects plus practical suggestions to cope with recurring communication problems.

Table of Contents

  1. Improving the content

  2. Improving the presentation

  3. Ensuring sustainability

  4. Communication mini-HOWTOs

    4.1 Bringing long topics to a conclusion

    4.2 Coping with flamewars

    4.3 Dealing with trolls


Taken from

Enrico Zini


ver. 0.1, 30 March, 2006

Copyright © 2005—2006 Enrico Zini

This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This is distributed in the hope that it will be useful, but without any warranty ; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

A copy of the GNU General Public License is available on the World Wide Web at the GNU web site.

Improving the content

The main part of communication is content, and the quality of the content is the main element that makes it useful.

If the quality of your posts is high, you go a long way towards getting what you want from your message. If the quality of your posts is usually low, people will slowly start skipping your messages, even if (and especially if) you post very often.

  • Ensure you are adding useful information
    Make sure that every single one of your posts contributes at least one piece of missing useful information.
    For example, “RTFM” without a precise pointer is not useful information: if someone already knew where to RTFM, they wouldn’t bother to ask.
    Try also not to repeat your points: when you have a good argument, idea or claim, let it be heard once. Only bring it up again if you can come up with code, specifications or technical explanations to back it up.

  • Share the help you receive
    Solving a problem creates knowledge, and it is important to share it. A useful IRC or email conversation can become a blog entry, a wiki page, a short tutorial or HOWTO.
    When you receive help, try to take notes of all it actually takes you to completely solve the problem, and share them.

  • Reuse existing resources
    When you are asking a question, do some research before posting: not only finding something on Google will give you an immediate answer, but it will avoid making people upset by asking the same question over and over again.
    Often you may end up reading a list archive with mails related to your problems. Follow the threads to learn more from the experiences of other people.
    If you see an error message you don’t understand, pasting it in the Google search field often gives you useful information.
    If you are replying to a question instead, a bit of research will allow you to provide a more precise answer.
    When you find useful informations, post pointers to existing resources.
    If a problem has already been solved or a point has already been made, post a link to the existing resource rather than repeating previous arguments.
    If the existing resource is not good enough, try to improve it: either in place (for example, if it is in a wiki) or by posting your further comments together with the link.

  • Know what you want and make sure people know what they want
    The biggest part in getting a good answer is to make a good question: try to work out what is that you really want. Ask yourself what are you really trying to get, where is that you are stuck, what were you expecting that did not happen. If you are lost, try asking yourself these four questions (this is called “Flanagan’s Critical Incident Technique”):

    • What led up to the situation?
    • What did you do that was especially effective or ineffective?
    • What was the outcome or result of this action?
    • Why was this action effective, or what more effective action might have been expected?

    The same questions are also useful to help clarify a situation when the other person is confused, and can be very handy when replying to a request for help or a bug report.

Improving the presentation

The way you present your content is also important. There is no absolute “most appropriate” way to present a content, but one has to choose what is better depending on who are the readers and what is the goal of the discussion.

In the case of technical discussion, what most people want is to quickly and efficiently find the best solution to a problem. Follows a list of style suggestions for contributing to a technical discussion:

  • Put the main point at the beginning, and the long details later.
    If people have to read through lots of text in order to get to the main point, they are likely to just skip the message if they are busy. Hook the readers in by stating the main point right away instead of trying to create expectation and surprise. You can even avoid posting about the long details and put them into the documentation instead.

  • Talk with code or patches.
    Wherever it is possible to use them, code or patches are the most efficient way of conveying technical information, and can also be used, applied or tested directly. Often patches are the preferred writing style: technical people tend to like to read code more than they like to read English, except when English is written inside code comments. Writing code is also useful to clear your own mind: while writing a piece of example code to show a problem, it is quite common to find the solution or to reframe the problem in a clearer way. Finally, some things are harder to explain in English rather than with code: so if there is something you have problems saying in English, try to say it using your favourite programming language.

  • Point to existing resources.
    If a problem has already been solved or a point has already been made, you can greatly condense your message by just posting a link to it. If the existing resource is not good enough, try to improve it: either in place (for example, if it is in a wiki) or by posting your further comments together with the link.

  • Use a plain and simple style
    People should spend their time answering your question or using your information, rather than understanding it.To help it, try to keep formalities to a minimum and avoid confusing people with rhetoric:

    • ask questions without asking if you can ask or apologising for asking. This may be impolite in real life, but it is generally the preferred way online.
    • if you are not a native English speaker, you don’t need to apologise for it: a minimal knowledge of the language is enough, as long as your mind is clear and you use a plain style. If English makes it really hard for you, try to use online translators like DeepL and write something in your language. Translators made really much progress for most language in the last couple of years.
    • Only ask a question if you want to know the answer: rhetorical questions often come across as unnecessarily confrontational, so avoid them if you can. If you have an opinion, just state it and ask for correction if needed.

Ensuring sustainability

While good messages are important, ensuring that the project keeps being a productive and fun place to be requires some care towards relationships with other people. This mainly boils down to being smart, honest and polite.

Most of the following suggestions are likely to be trivial for everyone, but they are worth collecting anyway so that we avoid forgetting some of them.

  • Read messages smartly.

    Most of the fun with working with others depends on how you read and interpret their messages and contributions:

    • Exercise your will.
      It is finally up to you to decide how a message is important and how it influences the way you do things.
      A message is ultimately important if it meets your needs and motivations: other aspects of it, such as if it is the last message in a thread or if it is full of convincing rhetoric or catchy phrases, have no relevance in a technical discussion.

    • Interact with human beings instead of single messages.
      When you see a message you don’t like, try to remember your general opinion of the person who wrote it. Try not to make a case about a single episode.
      If you see a message you don’t like written by a person you don’t know, wait to see some more posts before making assumptions about the person.
      If people do something that seriously undermines your trust or opinion of them, try writing them privately to tell about your disappointment and ask about their reasons.
      Also, try to remember who is normally doing good work and who is normally being a troll.

    • Be forgiving.
      Try to be tolerant towards others; when you are unsure about the intentions of a message, assume good intentions.

    • Be tolerant of personal differences.
      Remember that you might be discussing with someone who normally looks, thinks or behaves very differently than you do.
      openage is a large project which involves people from different cultures and with different beliefs. Some of these beliefs are understood to be in open conflict, but people still manage to have a fruitful technical cooperation.
      It is normal to dislike someone’s beliefs but still to appreciate their technical work. It would be a loss if a good technical work is not appreciated because of the beliefs of its contributor.

  • Be positive before being negative
    Try to put positive phrases before negative phrases: the result is more rewarding and pleasant to read.
    This can make a difference between a bug report that looks like an insult and a bug report that motivates developers to carry on their work.
    It is an interesting and at times difficult challenge to do it: you can look at how these guidelines are written to see examples.
    One reason this is hard to do is because most of the work with software is about problems. For example, most of the conversations in the Bug Tracking System start with telling that something does not work, or does not work as expected.
    This naturally leads us to mainly talk about problems, forgetting to tell us when things work, or when we appreciate the work of someone.

  • Give credit where credit is due.
    Always acknowledge useful feedback or patches in changelogs, documentation or other publicly visible places.
    Even if you personally do not care about attribution of work you’ve done, this may be very different for the other person you’re communicating with.
    openage is an effort people pursue in their free time, and getting an acknowledgement is often a nice reward, or an encouragement for people to get more involved.

  • Be respectful and polite.
    If you write in an unpleasant manner, people won’t feel motivated to work with you.

  • Help the public knowledge evolve.

    • Reply to the list.
      If you can help, do it in public: this will allow more people to benefit from the help, and to build on top of your help. For example they can add extra information to it, or use parts of your message to build an FAQ.

    • Encourage people to share the help they receive.
      Solving a problem creates knowledge, and it is important to share it. A useful IRC or email conversation can become a blog entry, a page in the docs with a short tutorial or HOWTO.
      When answering a question, you can ask the person to take notes about what it takes to actually completely solve the problem, and share them.

    • Sustaining a discussion towards solving a problem is sometimes more important than solving the problem.
      The most important thing in a technical discussion is that it keeps going towards a solution.
      Sometimes we see a discussion and we can foresee a solution, but we do not have the time to sort out the details.
      In such a case, there is a tendency to postpone answering until when one has the time to create a proper answer with the optimal solution in it.
      The risk is that the time never comes, or we get carried away by other things, and everything we had in mind gets lost.
      When there is this risk, keeping the discussion going towards solving the problem is more important than working silently towards the solution.

  • Judge the work and not the people.
    Judging work is easier than judging people, and in a technical community it is also more appropriated.
    Also, remember that human nature can be strange:

    • If I get told “your program does not work”, I am encouraged to fix it.
    • If I get told “you suck”, I am encouraged to go and work somewhere else.
    • If I get told “your program is great”, I am encouraged to write more.
    • If I get told “you are great”, I don’t need to work anymore to be cool.

Communication mini-HOWTOs

This chapter provides a small collection of practical suggestions on how to cope with specific repeating issues

Bringing long topics to a conclusion

Long topics with points being repeated over and over are an annoying waste of time. They however tend to happen from time to time, especially about important and controversial topics where a consensus is not easy to reach.

This is a collection of suggestions for coping with it:

  • Discuss controversial points off the forum with the people you disagree with.
    This would make it easier for you both to reach some consensus which is satisfactory for both.

  • Take a leadership role
    Step forward, take the good ideas that were spoken in the topic and work to put them into practice. This is good if good ideas have been spoken but the discussion keeps going with nothing else coming out, or in case of a topic that tends to be recurring over time. You can also put together a group of interested people to work on the issue. You can do it by taking the lead, contacting one by one the other active people in the topic to see if they are interested, making a public announcement to let people know and ask if more want to join.

  • Make summaries
    Summarise important parts of the topic and make them available to everyone, so that they don’t have to be repeated again. This can be done for recurring points, or if the topic reaches a useful point, or a consensus. The summary can be done inside our repository in the doc-folder for later use in our Sphinx documentation.

  • Start a new thread when the discussion drifts away
    Sometimes the discussion in a thread drifts away from the original topic to something related, or even unrelated. When this happens, do your best to reply starting a new topic. If it’s going to far off-topic consider discussing that topic in personal somewhere else.

Coping with flamewars

Stopping a flamewar is hard, but one can try to slow it down. A good way is to send a private mail to some of the most heated posters, such as:

This is off-list. What I think of the situation is [short summary]. However, this discussion is not being useful anymore: please drop the thread. Best wishes,

This will tell them that the thread is becoming annoying, and also offer them a chance to continue with the discussion off-list.

Posting a public message asking people to stop the thread does not work, and usually creates even more unwanted traffic. See the example “let’s not drag this into another flame war please” thread on debian-curiosa.

Another useful way of using private messages is to contact friends if they are being unconstructive or “flameish”. This would be better done when you otherwise agree with their point, so that the remark can be fully about how they are saying things rather than about what they are saying.

Dealing with trolls

Internet trolls are a fairly rare but very annoying phenomenon.

The best way to handle them is of course to ignore them to avoid giving them visibility. This can however be very difficult to do, because they tend to be very good at irritating people where they are most sensitive.

Consider giving the staff a chance to remove an evident troll message from the list archives just like they can do with spam: it is easy for them to get rid of it if it stays unanswered, but it becomes very hard if there are replies.

If you have an irresistible urge to react, do it by supporting the offended party, rather than attacking the troll (see Main guidelines ).

If the result of a provocation is not to cause trouble on the intended victims but rather to have them supported and encouraged, then the provocation has totally failed, and something useful happened in the meantime.