|Version 3 (modified by dkg, 6 years ago) (diff)|
In an age of information overload, we need...
Here are some reasonable suggestions for how to communicate with other humans on a cognitively-saturated network. These notes are currently disorganized, but they'll gradually get whipped into shape.
Since these are general principles, theses suggestions should be relevant to many different types of communication on a busy network:
- personal e-mail
- group mailing lists
- announcement lists
- web forums or bulletin boards
Quote relevant parts of any message you're responding to.
Trim (remove) things you aren't responding to.
Reply inline -- don't top post. It's difficult for someone coming late to the conversation to follow it if they have to read backwards.
Make it easy for the reader to distinguish between your text and quoted text. The traditional way to do this is with a "quotation" character (usually "> ") at the start of every quoted line. When replying inline in a plaintext medium such as e-mail, leave a single blank line between the quoted text and your response.
Put the crux of the issue first, if possible. a one or two-sentence description will help people know what's going on without wading through the full post.
Keep it short! if there are long snippets of pasted material, make sure those are clearly delimited so that the eye can skip them if it's just looking for the natural language stuff (or vice versa).
If you have a large piece of data that you think is relevant, don't include it directly in the message: place it somewhere on the web and include a link to it for people to fetch it as they see fit.
Do polite line wrapping: If you are using a plaintext medium such as e-mail, wrap any natural-language text (including quoted text, if possible) at reasonable widths (~72 chars is reasonable).
Choose a good subject! This may be the only thing people see of your message. Think about how your subject will be read by someone who is not themselves in the throes of your particular crisis. Subjects like "Help!" or "Big-time Problems" or "It's all broken..." don't give the reader any clue about what's happening, even if they do more adequately describe your emotional state.
create clear sections and subsections if your post gets too long. For example, if your reader sees "Summary", "Detailed Diagnosis", and "Fixes i've tried" sections, they'll be able to navigate your request more quickly.
If you have several inter-related questions or points, separate them with bullets or numbers. It's easier to respond to individual items if they are broken out like this.
When asking for technical advice or help
Include explicit transcripts of the transactions which you think failed.
If you know of any logs that might be relevant, try to include reasonable snippets of those logs.
Include your best shot at a natural language description of what you think is going on. Don't be afraid to misuse terms you aren't sure about, and ask for help characterizing the problem if you're not sure about it. Feel free to indicate when you're not sure whether something you're saying makes sense. The medical SOAP Note is an interesting model to consider.
do not line wrap machine-generated material (console transcripts, logs, etc). It makes it more difficult for your readers to tell what's going on if they have to sort out the line wrapping for themselves. you want folks to spend their time thinking about your problem, not the placement of carriage returns.
Include references to research you've done. If you've found web pages that seem relevant, but only take you part of the way, include their URLs in your message, and a brief note about what you got (or didn't get) from them.
Describe the overall context briefly. Not too much detail, but enough that people who have done similar projects can helpfully propose alternatives you've never even thought of. If you're trying to get a new version of python installed, but are're getting stuck on a filesystem permissions error you don't understand, mention the python install, not just the permissions error!
Read any responses with an open mind, even ones that recommend you take a path you thought you'd ruled out before.
If something in a response isn't clear, ask for a clarification!
Whether you fix the problem by yourself, or with the help of some of the responses, followup so other folks know it's been resolved. Saying thank you to people who helped is a really good idea: it encourages further help, and it sets a polite, friendly tone in whatever forum you're using, which encourages further politeness.