Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/more/discussion_policy.htm @ 44

Last change on this file since 44 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 15.3 KB
RevLine 
[29]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<html>
4<head>
5  <meta http-equiv="Content-Language" content="en-us">
6  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
7
8  <meta name="generator" content="Microsoft FrontPage 6.0">
9  <meta name="ProgId" content="FrontPage.Editor.Document">
10
11  <title>Boost Discussion Policy</title>
12</head>
13
14<body bgcolor="#FFFFFF" text="#000000">
15  <table border="1" bgcolor="#007F7F" cellpadding="2" summary="">
16    <tr>
17      <td bgcolor="#FFFFFF"><img src="../boost.png" alt=
18      "boost.png (6897 bytes)" width="277" height="86"></td>
19
20      <td><a href="../index.htm"><font face="Arial" color=
21      "#FFFFFF"><big>Home</big></font></a></td>
22
23      <td><a href="../libs/libraries.htm"><font face="Arial" color=
24      "#FFFFFF"><big>Libraries</big></font></a></td>
25
26      <td><a href="../people/people.htm"><font face="Arial" color=
27      "#FFFFFF"><big>People</big></font></a></td>
28
29      <td><a href="faq.htm"><font face="Arial" color=
30      "#FFFFFF"><big>FAQ</big></font></a></td>
31
32      <td><a href="index.htm"><font face="Arial" color=
33      "#FFFFFF"><big>More</big></font></a></td>
34    </tr>
35  </table>
36
37  <h1>Boost Discussion Policy</h1>
38
39  <p>Email discussion is the tie that binds boost members together into a
40  community. If the discussion is stimulating and effective, the community
41  thrives. If the discussion degenerates into name calling and ill will, the
42  community withers and dies.</p>
43
44  <h2>Contents</h2>
45
46  <dl>
47    <dt><a href="#acceptable">Acceptable Topics</a></dt>
48
49    <dt><a href="#unacceptable">Unacceptable Topics</a></dt>
50
51    <dt><a href="#effective">Effective Posting</a></dt>
52
53    <dt><a href="#behavior">Prohibited Behavior</a></dt>
54
55    <dt><a href="#culture">Culture</a></dt>
56
57    <dt><a href="#lib_names">Library Names</a></dt>
58  </dl>
59
60  <h2><a name="acceptable" id="acceptable"></a>Acceptable topics</h2>
61
62  <ul>
63    <li>Queries to determine interest in a possible library submission.</li>
64
65    <li>Technical discussions about a proposed or existing library, including
66    bug reports and requests for help.</li>
67
68    <li>Formal Reviews of proposed libraries.</li>
69
70    <li>Reports of user experiences with Boost libraries.</li>
71
72    <li>Boost administration or policies.</li>
73
74    <li>Compiler specific workarounds as applied to Boost libraries.</li>
75  </ul>
76
77  <p>Other topics related to boost development may be acceptable, at the
78  discretion of moderators. If unsure, go ahead and post. The moderators will
79  let you know.</p>
80
81  <h2><a name="unacceptable" id="unacceptable"></a>Unacceptable Topics</h2>
82
83  <ul>
84    <li>Advertisements for commercial products.</li>
85
86    <li>Requests for help getting non-boost code to compile with your
87    compiler. Try the comp.lang.c++.moderated newsgroup instead.</li>
88
89    <li>Requests for help interpreting the C++ standard. Try the comp.std.c++
90    newsgroup instead.</li>
91
92    <li>Job offers.</li>
93
94    <li>Requests for solutions to homework assignments.</li>
95  </ul>
96
97  <h2><a name="effective" id="effective"></a>Effective Posting</h2>
98
99  <p>Most Boost mailing lists host a great deal of traffic, so your post is
100  usually competing for attention with many other communications. This
101  section describes how to make sure it has the desired impact.</p>
102
103  <h3>Well-Crafted Posting is Worth the Effort</h3>
104
105  <p>Don't forget, you're a single writer but there are many readers, and you
106  want them to stay interested in what you're saying. Saving your readers a
107  little time and effort is usually worth the extra time you spend when
108  writing a message. Also, boost discussions are saved for posterity, as
109  rationales and history of the work we do. A post's usefulness in the future
110  is determined by its readability.</p>
111
112  <h3>Put the Library Name in the Subject Line</h3>
113
114  <p>When your post is related to a particular Boost library, it's helpful to
115  put the library name in square brackets at the beginning of the subject
116  line, e.g.</p>
117
118  <blockquote>
119    Subject: [Regex] Why doesn't this pattern match?
120  </blockquote>The Boost developers' list is a high-volume mailing list, and
121  most maintainers don't have time to read every message. A tag on the
122  subject line will help ensure the right people see your post.
123
124  <p><a name="tabs" id="tabs"></a></p>
125
126  <h3>Don't Use Tabs</h3>If you use tabs to indent your source code, convert
127  them to spaces before inserting the code in a posting. Something in the
128  processing chain usually strips all the indentation and leaves a mess
129  behind.
130
131  <p><a name="longlines" id="longlines"></a></p>
132
133  <h3>Limit Line Length</h3>If you put source code in your postings and your
134  mailer wraps long lines automatically, either keep the code narrow or
135  insert the code as an (inline, if possible) attachment. That will help
136  ensure others can read what you've posted.
137
138  <p><a name="quoting" id="quoting"></a></p>
139
140  <h3>Don't Overquote</h3>Please <b>prune extraneous quoted text</b> from
141  replies so that only the relevant parts are included. Some people have to
142  pay for, or wait for, each byte that they download from the list. More
143  importantly, it will save time and make your post more valuable when
144  readers do not have to find out which exact part of a previous message you
145  are responding to.
146
147  <h3>Use a Readable Quotation Style</h3>
148
149  <p>A common and very useful approach is to cite the small fractions of the
150  message you are actually responding to and to put your response directly
151  beneath each citation, with a blank line separating them for
152  readability:</p>
153
154  <blockquote>
155    <pre>
156<i>Person-you're-replying-to</i> wrote:
157
158&gt; Some part of a paragraph that you wish to reply to goes
159&gt; here; there may be several lines.
160
161Your response to that part of the message goes here.  There may,
162of course, be several lines.
163
164&gt; The second part of the  paragraph that is relevant to your
165&gt; reply goes here; agiain there may be several lines.
166
167Your response to the second part of the message goes here.
168...
169
170</pre>
171  </blockquote>For more information about effective use of quotation in
172  posts, see <a href="http://www.netmeister.org/news/learn2quote.html">this
173  helpful guide</a>.
174
175  <h3>Keep the Formatting of Quotations Consistent</h3>
176
177  <p>Some email and news clients use poor word wrapping algorithms that leave
178  successive lines from the same quotation with differing numbers of leading
179  "<tt>&gt;</tt>" characters. <b>Microsoft Outlook</b> and <b>Outlook
180  Express</b>, and some web clients, are especially bad about this. If your
181  client offends in this way, please take the effort to clean up the mess it
182  makes in quoted text. Remember, even if you didn't write the original text,
183  it's <i>your</i> posting; whether you get your point across depends on its
184  readability.</p>
185
186  <p>The Microsoft clients also create an unusually verbose header at the
187  beginning of the original message text and leave the cursor at the
188  beginning of the message, which encourages users to write their replies
189  before all of the quoted text rather than putting the reply in context.
190  Fortunately, Dominic Jain has written a utility that fixes all of these
191  problems automatically: <a href=
192  "http://home.in.tum.de/~jain/software/outlook-quotefix/">Outlook
193  Quotefix</a> for Outlook Users and <a href=
194  "http://home.in.tum.de/~jain/software/oe-quotefix/">OE QuoteFix</a> for
195  users of Outlook Express.</p>
196
197  <h3>Summarizing and Referring to Earlier Messages</h3>
198
199  <p>A summary of the foregoing thread is only needed after a long
200  discussion, especially when the topic is drifting or a result has been
201  achieved in a discussion. The mail system will do the tracking that is
202  needed to enable mail readers to display message threads (and every decent
203  mail reader supports that).</p>
204
205  <p>If you ever have to refer to single message earlier in a thread or in a
206  different thread then you can use a URL to the <a href=
207  "mailing_lists.htm#archive">message archives</a>. To help to keep those
208  URLs short, you can use <a href="http://www.tinyurl.com">tinyurl.com</a>.
209  Citing the relevant portion of a message you link to is often helpful (if
210  the citation is small).</p>
211
212  <h3>Maintain the Integrity of Discussion Threads</h3>
213
214  <p><b>When starting a new topic, always send a fresh message</b>, rather
215  than beginning a reply to some other message and replacing the subject and
216  body. Many mailers are able to detect the thread you started with and will
217  show the new message as part of the original thread, which probably isn't
218  what you intended. Follow this guideline for your own sake as well as for
219  others'. Often, people scanning for relevant messages will decide they're
220  done with a topic and hide or kill the entire thread: your message will be
221  missed, and you won't get the response you're looking for.</p>
222
223  <p>By the same token, <b>When replying to an existing message, use your
224  mailer's "Reply" function</b>, so that the reply shows up as part of the
225  same discussion thread.</p>
226
227  <p><b>Do not reply to digests</b> if you are a digest delivery subscriber.
228  Your reply will not be properly threaded and will probably have the wrong
229  subject line. Instead, you can reply through the <a href=
230  "http://news.gmane.org/gmane.comp.lib.boost.devel">GMane web
231  interface</a>.</p>
232
233  <h3>Keep The Size of Your Posting Manageable</h3>
234
235  <p>The mailing list software automatically limits message and attachment
236  size to a reasonable amount, typically 75K, which is adjusted from
237  time-to-time by the moderators. This limit is a courtesy to those who rely
238  on dial-up Internet access.</p>
239
240  <h2><a name="behavior" id="behavior"></a>Prohibited Behavior</h2>
241
242  <p>Prohibited behavior will not be tolerated. The moderators will ban
243  postings by abusers.</p>
244
245  <h3>Flame wars</h3>
246
247  <p>Personal insults, argument for the sake of argument, and all the other
248  behaviors which fall into the "flame war" category are prohibited.
249  Discussions should focus on technical arguments, not the personality traits
250  or motives of participants.</p>
251
252  <h3>Third-party attacks</h3>
253
254  <p>Attacks on third parties such as software vendors, hardware vendors, or
255  any other organizations, are prohibited. Boost exists to unite and serve
256  the entire C++ community, not to disparage the work of others.</p>
257
258  <p>Does this mean that we ban the occasional complaint or wry remark about
259  a troublesome compiler? No, but be wary of overdoing it.</p>
260
261  <h3>Off-topic posts</h3>
262
263  <p>Discussions which stray from the acceptable topics are strongly
264  discouraged. While off-topic posts are often well meaning and not as
265  individually corrosive as other abuses, cumulatively the distraction
266  damages the effectiveness of discussion.</p>
267
268  <h2><a name="culture" id="culture"></a>Culture</h2>
269
270  <p>In addition to technical skills, Boost members value collaboration,
271  acknowledgement of the help of others, and a certain level of politeness.
272  Boost membership is very international, and ranges widely in age and other
273  characteristics. Think of discussion as occurring among colleagues in a
274  widely read forum, rather than among a few close friends.</p>
275
276  <p>Always remember that the cumulative effort spent by people reading your
277  contribution scales with the (already large) number of boost members. Thus,
278  do invest time and effort to make your message as readable as possible.
279  Adhere to English syntax and grammar rules such as proper capitalization.
280  Avoid copious informalism, colloquial language, or abbreviations, they may
281  not be understood by all readers. Re-read your message before submitting
282  it.</p>
283
284  <h2>Guidelines for Effective Discussions</h2>
285
286  <p>Apply social engineering to prevent heated technical discussion from
287  degenerating into a shouting match, and to actively encourage the
288  cooperation upon which Boost depends.</p>
289
290  <ul>
291    <li>Questions help. If someone suggests something that you don't think
292    will work, then replying with a question like "will that compile?" or
293    "won't that fail to compile, or am I missing something?" is a lot
294    smoother than "That's really stupid - it won't compile."&nbsp; Saying
295    "that fails to compile for me, and seems to violate section n.n.n of the
296    standard" would be yet another way to be firm without being
297    abrasive.</li>
298
299    <li>If most of the discussion has been code-free generalities, posting a
300    bit of sample code can focus people on the practical issues.</li>
301
302    <li>If most of the discussion has been in terms of specific code, try to
303    talk a bit about hidden assumptions and generalities that may be
304    preventing discussion closure.</li>
305
306    <li>Taking a time-out is often effective. Just say: "Let me think about
307    that for a day or two. Let's take a time-out to digest the discussion so
308    far."</li>
309  </ul>
310
311  <p>Avoid <i><b>Parkinson's Bicycle Shed</b></i>. Parkinson described a
312  committee formed to oversee design of an early nuclear power plant. There
313  were three agenda items - when to have tea, where to put the bicycle shed,
314  and how to ensure nuclear safety. Tea was disposed of quickly as
315  trivial.&nbsp;Nuclear safety was discussed for only an hour - it was so
316  complex, scary, and technical that even among experts few felt comfortable
317  with the issues. Endless days were then spent discussing construction of
318  the bicycle shed (the parking lot would be the modern equivalent) because
319  everyone though they understood the issues and felt comfortable discussing
320  them.&nbsp;</p>
321
322  <h2><a name="lib_names" id="lib_names"></a>Library Names</h2>
323
324  <p>In order to ensure a uniform presentation in books and articles, we have
325  adopted a convention for referring to Boost libraries. Library names can
326  either be written in a compact form with a dot, as "Boost.<i>Name</i>", or
327  in a long form as "the Boost <i>Name</i> library." For example:</p>
328
329  <blockquote>
330    <b>Boost.Python</b> serves a very different purpose from <b>the Boost
331    Graph library</b>.
332  </blockquote>Note that the word "library" is not part of the name, and as
333  such isn't capitalized.
334
335  <p>Please take care to avoid confusion in discussions between libraries
336  that have been accepted into Boost and those that have not. Acceptance as a
337  Boost library indicates that the code and design have passed through our
338  peer-review process; failing to make the distinction devalues the hard work
339  of library authors who've gone through that process. Here are some
340  suggested ways to describe potential Boost libraries:</p>
341
342  <ul>
343    <li>the proposed Boost <i>Name</i> library</li>
344
345    <li>the Boost.<i>Name</i> candidate</li>
346
347    <li>the <i>Name</i> library (probably the best choice where
348    applicable)</li>
349  </ul>
350
351  <p>Note that this policy only applies to discussions, not to the
352  documentation, directory structure, or even identifiers in the code of
353  potential Boost libraries.</p>
354  <hr>
355
356  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
357  "http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
358  height="31" width="88"></a></p>
359
360  <p>Revised
361  <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->04 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
362
363  <p><i>Copyright &copy; 2000-2005 Beman Dawes, Rob Stewart, and David Abrahams</i></p>
364
365  <p><i>Distributed under the Boost Software License, Version 1.0. (See
366  accompanying file <a href="../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy
367  at <a href=
368  "http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</i></p>
369</body>
370</html>
Note: See TracBrowser for help on using the repository browser.