Boost Discussion Policy
Email discussion is the tie that binds boost members together into a community. If the discussion is stimulating and effective, the community thrives. If the discussion degenerates into name calling and ill will, the community withers and dies.
- Acceptable Topics
- Unacceptable Topics
- Effective Posting
- Well-Crafted Posting is Worth the Effort
- Put the Library Name in the Subject Line
- Don't Use Tabs
- Limit Line Length
- Don't Overquote, Don't Top-Post, and Do Use Inline Replies for Readable Quotations
- Keep the Formatting of Quotations Consistent
- Summarizing and Referring to Earlier Messages
- Maintain the Integrity of Discussion Threads
- Keep The Size of Your Posting Manageable
- Prohibited Behavior
- Guidelines for Effective Discussions
- Library Names
- Queries to determine interest in a possible library submission.
- Technical discussions about a proposed or existing library, including bug reports and requests for help.
- Formal Reviews of proposed libraries.
- Reports of user experiences with Boost libraries.
- Boost administration or policies.
- Compiler specific workarounds as applied to Boost libraries.
Other topics related to boost development may be acceptable, at the discretion of moderators. If unsure, go ahead and post. The moderators will let you know.
- Advertisements for commercial products.
- Requests for help getting non-boost code to compile with your compiler. Try the comp.lang.c++.moderated newsgroup instead.
- Requests for help interpreting the C++ standard. Try the comp.std.c++ newsgroup instead.
- Job offers.
- Requests for solutions to homework assignments.
Most Boost mailing lists host a great deal of traffic, so your post is usually competing for attention with many other communications. This section describes how to make sure it has the desired impact.
Don't forget, you're a single writer but there are many readers, and you want them to stay interested in what you're saying. Saving your readers a little time and effort is usually worth the extra time you spend when writing a message. Also, boost discussions are saved for posterity, as rationales and history of the work we do. A post's usefulness in the future is determined by its readability.
When your post is related to a particular Boost library, it's helpful to put the library name in square brackets at the beginning of the subject line, e.g.
Subject: [Regex] Why doesn't this pattern match?
The Boost developers' list is a high-volume mailing list, and most maintainers don't have time to read every message. A tag on the subject line will help ensure the right people see your post.
If you use tabs to indent your source code, convert them to spaces before inserting the code in a posting. Something in the processing chain usually strips all the indentation and leaves a mess behind.
If you put source code in your postings and your mailer wraps long lines automatically, either keep the code narrow or insert the code as an (inline, if possible) attachment. That will help ensure others can read what you've posted.
Please prune extraneous quoted text from replies so that only the relevant parts are included. Some people have to pay for, or wait for, each byte that they download from the list. More importantly, it will save time and make your post more valuable when readers do not have to find out which exact part of a previous message you are responding to.
The common and very useful inline approach cites the small fractions of the message you are actually responding to and puts your response directly beneath each citation, with a blank line separating them for readability:
Person-you're-replying-to wrote: > Some part of a paragraph that you wish to reply to goes > here; there may be several lines. Your response to that part of the message goes here. There may, of course, be several lines. > The second part of the paragraph that is relevant to your > reply goes here; agiain there may be several lines. Your response to the second part of the message goes here. ...
For more information about effective use of quotation in posts, see this helpful guide.
Some email and news clients use poor word wrapping
algorithms that leave successive lines from the same quotation
with differing numbers of leading "
characters. Microsoft Outlook and
Outlook Express, and some web clients, are
especially bad about this. If your client offends in this way,
please take the effort to clean up the mess it makes in quoted
text. Remember, even if you didn't write the original text,
it's your posting; whether you get your point across
depends on its readability.
The Microsoft clients also create an unusually verbose header at the beginning of the original message text and leave the cursor at the beginning of the message, which encourages users to write their replies before all of the quoted text rather than putting the reply in context. Fortunately, Dominic Jain has written a utility that fixes all of these problems automatically: Outlook Quotefix for Outlook Users and OE QuoteFix for users of Outlook Express.
A summary of the foregoing thread is only needed after a long discussion, especially when the topic is drifting or a result has been achieved in a discussion. The mail system will do the tracking that is needed to enable mail readers to display message threads (and every decent mail reader supports that).
If you ever have to refer to single message earlier in a thread or in a different thread then you can use a URL to the message archives. To help to keep those URLs short, you can use tinyurl.com. Citing the relevant portion of a message you link to is often helpful (if the citation is small).
When starting a new topic, always send a fresh message, rather than beginning a reply to some other message and replacing the subject and body. Many mailers are able to detect the thread you started with and will show the new message as part of the original thread, which probably isn't what you intended. Follow this guideline for your own sake as well as for others'. Often, people scanning for relevant messages will decide they're done with a topic and hide or kill the entire thread: your message will be missed, and you won't get the response you're looking for.
By the same token, When replying to an existing message, use your mailer's "Reply" function, so that the reply shows up as part of the same discussion thread.
Do not reply to digests if you are a digest delivery subscriber. Your reply will not be properly threaded and will probably have the wrong subject line. Instead, you can reply through the GMane web interface.
The mailing list software automatically limits message and attachment size to a reasonable amount, typically 75K, which is adjusted from time-to-time by the moderators. This limit is a courtesy to those who rely on dial-up Internet access, and let's face it, no one wants to read a posting that consists of 75K of error message text.
Prohibited behavior will not be tolerated. The moderators will ban postings by abusers.
Personal insults, argument for the sake of argument, and all the other behaviors which fall into the "flame war" category are prohibited. Discussions should focus on technical arguments, not the personality traits or motives of participants.
Attacks on third parties such as software vendors, hardware vendors, or any other organizations, are prohibited. Boost exists to unite and serve the entire C++ community, not to disparage the work of others.
Does this mean that we ban the occasional complaint or wry remark about a troublesome compiler? No, but be wary of overdoing it.
Discussions which stray from the acceptable topics are strongly discouraged. While off-topic posts are often well meaning and not as individually corrosive as other abuses, cumulatively the distraction damages the effectiveness of discussion.
In addition to technical skills, Boost members value collaboration, acknowledgement of the help of others, and a certain level of politeness. Boost membership is very international, and ranges widely in age and other characteristics. Think of discussion as occurring among colleagues in a widely read forum, rather than among a few close friends.
Always remember that the cumulative effort spent by people reading your contribution scales with the (already large) number of boost members. Thus, do invest time and effort to make your message as readable as possible. Adhere to English syntax and grammar rules such as proper capitalization. Avoid copious informalism, colloquial language, or abbreviations, they may not be understood by all readers. Re-read your message before submitting it.
Apply social engineering to prevent heated technical discussion from degenerating into a shouting match, and to actively encourage the cooperation upon which Boost depends.
- Questions help. If someone suggests something that you don't think will work, then replying with a question like "will that compile?" or "won't that fail to compile, or am I missing something?" is a lot smoother than "That's really stupid - it won't compile." Saying "that fails to compile for me, and seems to violate section n.n.n of the standard" would be yet another way to be firm without being abrasive.
- If most of the discussion has been code-free generalities, posting a bit of sample code can focus people on the practical issues.
- If most of the discussion has been in terms of specific code, try to talk a bit about hidden assumptions and generalities that may be preventing discussion closure.
- Taking a time-out is often effective. Just say: "Let me think about that for a day or two. Let's take a time-out to digest the discussion so far."
Avoid Parkinson's Bicycle Shed. Parkinson described a committee formed to oversee design of an early nuclear power plant. There were three agenda items - when to have tea, where to put the bicycle shed, and how to ensure nuclear safety. Tea was disposed of quickly as trivial. Nuclear safety was discussed for only an hour - it was so complex, scary, and technical that even among experts few felt comfortable with the issues. Endless days were then spent discussing construction of the bicycle shed (the parking lot would be the modern equivalent) because everyone though they understood the issues and felt comfortable discussing them.
In order to ensure a uniform presentation in books and articles, we have adopted a convention for referring to Boost libraries. Library names can either be written in a compact form with a dot, as "Boost.Name", or in a long form as "the Boost Name library." For example:
Boost.Python serves a very different purpose from the Boost Graph library.
Note that the word "library" is not part of the name, and as such isn't capitalized.
Please take care to avoid confusion in discussions between libraries that have been accepted into Boost and those that have not. Acceptance as a Boost library indicates that the code and design have passed through our peer-review process; failing to make the distinction devalues the hard work of library authors who've gone through that process. Here are some suggested ways to describe potential Boost libraries:
- the proposed Boost Name library
- the Boost.Name candidate
- the Name library (probably the best choice where applicable)
Note that this policy only applies to discussions, not to the documentation, directory structure, or even identifiers in the code of potential Boost libraries.