diff options
Diffstat (limited to 'more/discussion_policy.htm')
| -rw-r--r-- | more/discussion_policy.htm | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/more/discussion_policy.htm b/more/discussion_policy.htm new file mode 100644 index 0000000000..b5d5d877ff --- /dev/null +++ b/more/discussion_policy.htm @@ -0,0 +1,305 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Boost Discussion Policy</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"> + <img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> + +<h1>Boost Discussion Policy</h1> +<p>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.</p> + +<h2>Contents</h2> +<dl> + <dt><a href="#acceptable">Acceptable Topics</a><dd> + <dt><a href="#unacceptable">Unacceptable Topics</a><dd> + <dt><a href="#effective">Effective Posting</a><dd> + <dt><a href="#behavior">Prohibited Behavior</a><dd> + <dt><a href="#culture">Culture</a><dd> + <dt><a href="#lib_names">Library Names</a><dd> + </dl> + +<h2><a name="acceptable"></a>Acceptable topics</h2> +<ul> + <li>Queries to determine interest in a possible library submission.</li> + <li>Technical discussions about a proposed or existing library, including bug + reports and requests for help.</li> + <li>Formal Reviews of proposed libraries.</li> + <li>Reports of user experiences with Boost libraries.</li> + <li>Boost administration or policies.</li> + <li>Compiler specific workarounds as applied to Boost libraries.</li> +</ul> +<p>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.</p> +<h2><a name="unacceptable"></a>Unacceptable Topics</h2> +<ul> + <li>Advertisements for commercial products.</li> + <li>Requests for help getting non-boost code to compile with your compiler. + Try the comp.lang.c++.moderated newsgroup instead.</li> + <li>Requests for help interpreting the C++ standard. Try the comp.std.c++ + newsgroup instead.</li> + <li>Job offers.</li> + <li>Requests for solutions to homework assignments.</ul> + +<h2><a name="effective"></a>Effective Posting</h2> + +<p>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. + +<h3>Well-Crafted Posting is Worth the Effort</h3> + +<p>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. + +<h3>Put the Library Name in the Subject Line</h3> + +<p>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. + +<blockquote> + Subject: [Regex] Why doesn't this pattern match? +</blockquote> + +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. + +<p><a name="quoting"></a> + +<h3>Don't Overquote</h3> +Please <b>prune extraneous quoted text</b> 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. + +<h3>Use a Readable Quotation Style</h3> +<p>A common and very useful approach is to cite the small fractions of +the message you are actually responding to and to put your response +directly beneath each citation, with a blank line separating them for +readability: + +<blockquote> +<pre> + +<i>Person-you're-replying-to</i> 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. +... + +</pre> +</blockquote> + +For more information about effective use of quotation in posts, see <a +href="http://www.netmeister.org/news/learn2quote.html">this helpful +guide</a>. + +<h3>Keep the Formatting of Quotations Consistent</h3> +<p> +Some email and news clients use poor word wrapping algorithms that +leave successive lines from the same quotation with differing numbers +of leading "<tt>></tt>" characters. <b>Microsoft +Outlook</b> and <b>Outlook Express</b>, 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 <i>your</i> +posting; whether you get your point across depends on its readability. +<p> +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. Outlook Express users can fix all of these problems +automatically by installing +<a href="http://home.in.tum.de/~jain/software/oe-quotefix/">OE +QuoteFix</a>. Unfortunately there's no similar utility for Outlook +Users; they will have to clean up their posts manually. + +<h3>Summarizing and Referring to Earlier Messages</h3> + +<p>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). + +<p>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 <a +href="mailing_lists.htm#archive">message archives</a>. To help to +keep those URLs short, you can use <a +href="http://www.tinyurl.com">tinyurl.com</a>. Citing the relevant +portion of a message you link to is often helpful (if the citation is +small). + +<h3>Maintain the Integrity of Discussion Threads</h3> + +<p><b>When starting a new topic, always send a fresh message</b>, +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. + +<p>By the same token, <b>When replying to an existing message, use +your mailer's "Reply" function</b>, so that the reply shows +up as part of the same discussion thread. + +<p><b>Do not reply to digests</b> 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 <a href="http://news.gmane.org/gmane.comp.lib.boost.devel">GMane +web interface</a>. + + +<h3>Keep The Size of Your Posting Manageable</h3> + +<p>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. +</p> + +<h2><a name="behavior"></a>Prohibited Behavior</h2> +<p>Prohibited behavior will not be tolerated. The moderators will ban +postings by abusers.</p> +<h3>Flame wars</h3> +<p>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.</p> +<h3>Third-party attacks</h3> +<p>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.</p> +<p>Does this mean that we ban the occasional complaint or wry remark about a +troublesome compiler? No, but be wary of overdoing it.</p> +<h3>Off-topic posts</h3> +<p>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.</p> +<h2><a name="culture"></a>Culture</h2> +<p>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.</p> + +<p>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.</p> + +<h2>Guidelines for Effective Discussions</h2> +<p>Apply social engineering to prevent heated technical discussion from +degenerating into a shouting match, and to actively encourage the cooperation +upon which Boost depends.</p> +<ul> + <li>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.</li> + <li>If most of the discussion has been code-free generalities, posting a bit + of sample code can focus people on the practical issues.</li> + <li>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.</li> + <li>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."</li> +</ul> +<p>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 where to put the bicycle shed (the parking lot would +be a modern equivalent) because everyone +understood the issues and felt comfortable discussing them. </p> + +<h2><a name="lib_names"></a>Library Names</h2> + +<p>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.<i>Name</i>", or in a long form as "the +Boost <i>Name</i> library." For example: +<blockquote> +<b>Boost.Python</b> serves a very different purpose from <b>the Boost Graph library</b>. +</blockquote> +Note that the word "library" is not part of the name, and as such isn't capitalized. + +<p>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: +<ul> + <li>the proposed Boost <i>Name</i> library</li> + <li>the Boost.<i>Name</i> candidate</li> + <li>the <i>Name</i> library</i> (probably the best choice where applicable)</li> +</ul> +<p>Note that this policy only applies to discussions, not to the +documentation, directory structure, or even identifiers in the +code of potential Boost libraries. + +<hr> +<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->28 May, 2005<!--webbot bot="Timestamp" i-checksum="38549" endspan --> +</p> +<p>© Beman Dawes, Rob Stewart, and David Abrahams 2000-2005</p> +<p> Distributed under the Boost Software License, Version 1.0. +(See accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or +copy at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>) +</p> + +</body> + +</html> |