|
|
Boost-Commit : |
From: daniel_james_at_[hidden]
Date: 2007-11-11 14:40:40
Author: danieljames
Date: 2007-11-11 14:40:39 EST (Sun, 11 Nov 2007)
New Revision: 41014
URL: http://svn.boost.org/trac/boost/changeset/41014
Log:
Update the discussion policy page on the beta site, and remove it from trunk.
Removed:
trunk/more/discussion_policy.htm
Deleted: trunk/more/discussion_policy.htm
==============================================================================
--- trunk/more/discussion_policy.htm 2007-11-11 14:40:39 EST (Sun, 11 Nov 2007)
+++ (empty file)
@@ -1,372 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
-<html>
-<head>
- <meta http-equiv="Content-Language" content="en-us">
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
-
- <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" summary="">
- <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>Acceptable Topics</dt>
-
- <dt>Unacceptable Topics</dt>
-
- <dt>Effective Posting</dt>
-
- <dt>Prohibited Behavior</dt>
-
- <dt>Culture</dt>
-
- <dt>Library Names</dt>
- </dl>
-
- <h2><a name="acceptable" id="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" id="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.</li>
- </ul>
-
- <h2><a name="effective" id="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.</p>
-
- <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.</p>
-
- <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.</p>
-
- <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="tabs" id="tabs"></a></p>
-
- <h3>Don't Use Tabs</h3>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.
-
- <p><a name="longlines" id="longlines"></a></p>
-
- <h3>Limit Line Length</h3>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.
-
- <p><a name="quoting" id="quoting"></a></p>
-
- <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>Don't <a href="http://en.wikipedia.org/wiki/Posting_style#Top-posting">
- top-post</a>; inline replies are the appropriate
- posting style for
- Boost lists.</p>
-
- <p>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:</p>
-
- <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>
-
- <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.
- Fortunately, Dominic Jain has written a utility that fixes all of these
- problems automatically: <a href=
- "http://home.in.tum.de/~jain/software/outlook-quotefix/">Outlook
- Quotefix</a> for Outlook Users and <a href=
- "http://home.in.tum.de/~jain/software/oe-quotefix/">OE QuoteFix</a> for
- users of Outlook Express.</p>
-
- <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>
-
- <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 tinyurl.com.
- Citing the relevant portion of a message you link to is often helpful (if
- the citation is small).</p>
-
- <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>
-
- <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>
-
- <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>.</p>
-
- <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" id="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" id="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 <i><b>Parkinson's Bicycle Shed</b></i>. 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. </p>
-
- <h2><a name="lib_names" id="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:</p>
-
- <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:</p>
-
- <ul>
- <li>the proposed Boost <i>Name</i> library</li>
-
- <li>the Boost.<i>Name</i> candidate</li>
-
- <li>the <i>Name</i> library (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.</p>
- <hr>
-
- <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
- "http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
- height="31" width="88"></a></p>
-
- <p>Revised
- <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->07 November, 2007<!--webbot bot="Timestamp" endspan i-checksum="39369" --></p>
-
- <p><i>Copyright © 2000-2005 Beman Dawes, Rob Stewart, and David Abrahams</i></p>
-
- <p><i>Distributed under the Boost Software License, Version 1.0. (See
- accompanying file LICENSE_1_0.txt or copy
- at <a href=
- "http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</i></p>
-</body>
-</html>
\ No newline at end of file
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk