I had an interesting experience over the summer, working in a small but diverse team on a single project for several months. I was contracted to design and maintain the build system, and so ended up getting involved in all areas of the project. As a result, I came across many of the problems which my team mates were having. A lot of these problems were my fault, some were my team mates’ faults; but a lot of the problems were a result of bad communication.
While this all occurred in a (unfortunately) closed source project, I’ve seen similar things happen in open source. I thought I’d come up with a list of suggestions for people starting out in the open source world, to try and help them understand the best way to interact with other people on the same project, or with their mentors in GSoC (for example). None of this is targeted at anyone in particular (especially not the GSoC students I had the pleasure of interacting with this summer)!
Thinking about this has been useful to me; hopefully I won’t do any of these things in future (because I certainly have in the past). I just hope it’s useful to someone, somewhere.
- Don’t spam chats with half-written messages. Take your time and formulate your thoughts properly in a full sentence. Spamming messages just means the other conversant has to sit there and wait for the rest of the sentence, rather than getting on with something else.
- Don’t join a chat, say “hi” or “someone please help” or “ping” and then sit there without giving more information. This just introduces an extraneous round trip in communication, since someone has to then ask what the problem is before they can start to help. Conversely, if someone joins a chat and says “someone please help”, don’t lecture them about it. Be patient, and help them as much as you can.
- After asking a question in a chat, wait patiently for the answer to the question. Although they’d love to help, developers are not constantly looking at their chat client. If you leave a fully-formed question in the chat and then wait, a developer should answer in their own time.
- If you encounter an error or warning (e.g. from a compiler or program) and want help with it, always provide the full error message and some context. The person who’s helping you isn’t psychic.
- Always give context and be careful of over-using pronouns. “It’s running awfully slow” is not specific enough. What is ‘it’? What were you doing with ‘it’ when things slowed down?
- Look at man pages and --help output before asking people. Documentation for established software (e.g. SVN) is generally quite good. The person who’s helping you will probably just look at the man page anyway.
- Read VCS commit logs. Ideally, people will explain and justify all of their work in their commit messages, and mention things which you should be aware of. Reading the logs may well save you debugging later.
- Use the correct terminology as much as possible, and don’t use that terminology in other contexts where it could confuse matters. Communication is a lot faster if a common vocabulary is used.
- Learn your version control system and learn it well. It’s a tool you’ll be using every day, and making mistakes with it can be costly for your (uncommitted) work and/or for other people’s productivity. Always check the changes you’re about to commit, especially if conflicts have occurred. People will not take kindly to their work being overwritten because you’ve made a mistake, especially if it happens regularly.
- If you’re making use of someone else’s code/APIs and you have a problem or can’t get it working, double check (against the documentation which they have written) that you’re using the code correctly. In many cases, the problem might be the way you’re invoking/using that code, not the work itself (thought such problems do suggest a lack of user friendliness in the work which could be fixed).
- Always check to see if the code at least compiles before committing it to VCS. Committing something which doesn’t compile due to a trivial error shows a complete lack of testing or care. Compile it using the build system which everyone else uses, too. Manually invoking the compiler doesn’t count.