On Mon, Sep 9, 2013 at 5:30 AM, Jorge Cardoso Leitao < jorgecarlei...@gmail.com> wrote:
> Hi Django dev mailing list. > > The objective of this email is two-fold: > A: I want to share a book I've read about written communication. Since > communication in Django, and open source in general, is mainly written, > some of you may found interesting to take a look. > B: I want to suggest adapting some of the book's content to Django's > documentation on a form of guidelines on how to communicate on the project > (skip to end of the mail if part A is not relevant for you). > > ---------- Start of part A ---------- > > The book's title is "How to Read a Book", is from 1940 and last revised in > 1972, and basically teaches one how to read (a book). > I find it more general to the extent that it teaches one on how to > communicate. > Here I highlight some of its points (the book can be found online here: > http://crap.sceleris.net/HowtoReadABook.pdf): > > 0. The book is about reading for *understanding*, as opposed to for > entertainment or for getting informed. > > ---------- Reading for understanding --------- > > 1. Understanding requires information and thought, but none of them is a > sufficient condition. It is sufficient to explain something in own words to > understand it. > > 2. from 1., any written text must have information, and every writer *and > reader* must think during writing and reading respectively. > > 3. Every (good) text has a unity (and not a multiplicity), and every unity > has a multiplicity (a set of sub-units). Each sub-unit has itself a unity. > This is repeated until the un-fractionable element of thought, the argument. > > Putting in other words: each book has a final conclusion. Each part of the > book has a conclusion that is one of the arguments to the > book's conclusion. Each chapter of each part has a conclusion that is > an argument to the part's conclusion, etc. This repeats itself (e.g. > chapters, sections, sub-sections, paragraphs) until the basic element: > an argument made out of prepositions and reasoning connecting prepositions. > > 4. The reader must be able to state the unity of the book and enumerate > the major parts that it is constituted before he starts reading it > (top-down approach). This is to avoid wasting time reading > an uninteresting book. > > 5. The reader must then reach the unity of each sub-unit by a bottom-up > approach: prepositions with reasoning generate arguments, arguments > generate conclusions of sub-units, which are arguments of larger sub-units. > At some point this meets the top-down approach (4.). If the reader can > state, by own words, how the author reached the book's unity by this > bottom-up construction, the authors claim he understood the book. > > ---------- After understanding, criticism... --------- > > 6. Do not begin criticism until you have completed your outline and your > interpretation of the book. (Do not say "I agree", "I disagree", or "I > suspend judgment", until you can say “I understand.”). > > 7. Do not disagree disputatiously or contentiously (e.g. only disagree if > you expect that some agreement will be possible). Here is a beautiful > passage on this: > > The trouble is that many people regard disagreement as unrelated to either > teaching or being taught. They think that everything is just a matter of > opinion. I have mine, and you have yours; and our right to our opinions is > as inviolable as our right to private property. On such a view, > communication cannot be profitable if the profit to be gained is an > increase in knowledge. Conversation is hardly better than a ping-pong game > of opposed opinions, a game in which no one keeps score, no one wins, and > everyone is satisfied because he does not lose—that is, he ends up holding > the same opinions he started with. > We would not—and could not—write this book if we held this view. Instead, > we hold that knowledge can be communicated and that discussion can result > in learning. If genuine knowledge, not mere personal opinion, is at stake, > then, for the most part, either disagreements are apparent only—to be > removed by coming to terms and a meeting of minds; or they are real, and > the genuine issues can be resolved—in the long run, of course—by appeals to > fact and reason. The maxim of rationality concerning disagreements is to be > patient for the long run. We are saying, in short, that disagreements are > arguable matters. And argument is empty unless it is undertaken on the > supposition that there is attainable an understanding that, when attained > by reason in the light of all the relevant evidence, resolves the original > issues. > > > These rules continues, specifically on what form one can disagree: > > 7.1. Author is uninformed (relevant information neglected) > > 7.2. Author is misinformed (wrong information) > > 7.3. Author is illogical (formal fallacy, e.g. (A=>B) => (~A => ~B), > typically difficult to find in written language) > > 7.4. Author's analysis is incomplete (most common, when the analysis does > not consider other important arguments). > > Each of these bullets, as well of each of the points I enumerated before, > are thoughtfully explained in the book. > > I argue that most of the book (specially the criticism part) is a nice > reading for those working on open source development because written > language is a major medium of communication (first objective of this mail). > > ------------ end part A, start of part B ------------ > > I think there are important points on the book that can be adapted to > Django's context and added to the documentation on how to use the project's > communications tools (second objective of this mail). > > This addresses the problem I had myself the first time I mailed this > mailing-list: I had no idea on how to communicate here and time was wasted > by me and you because of that. > > Specifically, my suggestion is to add a new section, probably in > https://docs.djangoproject.com/en/dev/internals/contributing/new-contributors/, > on how to communicate in this project (which should be similar to other > open source projects). > > Thus, I would like to open the discussion: does anyone see any relevance > in adding guidelines on how to use Django's communications tools, e.g. from > the perspective I presented in part A? > I think this book is a good starting point. I also read "Producing Open > Source Software" from Karl Fogel (Subversion), which also has insightful > points on the topic (Chap. communication). > > Hope this also generates some curiosity on the topic :-) > Hi Jorge, Thanks for putting this all together. There's some useful information in here, which is worth absorbing from a personal development perspective. However, I'm deeply sceptical that any of this material has a place in Django's own documentation. There's very no point padding Django's documentation with preachy statements about "how to communicate properly" -- because no matter how much we might like it to be, reading the documentation isn't a pre-requisite for trying to contribute to Django. It *should* be, and I certainly encourage anyone who wants to get involved to read the docs, but experience clearly demonstrates that many first-time contributors haven't read the docs. Some examples: * The "new ticket" page says "PLEASE DON'T REPORT SECURITY ISSUES HERE" -- and yet, a couple of times a year, someone reports a security problem on Trac. * The description for the django-developers mailing list reads "This group is for the discussion of the development of Django itself. If you want to ask questions about using Django, please post on django-users" and yet, we'll get half a dozen messages every week that are posted to django-dev and should be on django-users. * The existing contributor docs say every patch *must* have docs and tests… and yet there are plenty of examples of patches in Trac that have no docs and tests, and a frustrated comment from a contributor saying "Why haven't you merged my patch". My point -- adding documentation on "how to communicate" won't magically fix anything. Documentation needs to be read, comprehended, and followed before it changes any behaviour. I've presented here several examples where the requested behaviour is well documented, and in 2 of 3 cases, put in front of the user right before they engage in action -- and yet they still ignore the advice. Worse still, I suspect it will be very hard to write the kind of documentation without appearing either preachy, or being nauseatingly dry (trying to use (A=>B) => (~A => ~B) in a sentence, for example). As an open source project, the only resource we have is social capital, and telling people "You're communicating wrong - do that again" isn't a productive way to engage those volunteer resources. With all that said, code talks. If you can present a patch that covers the sort of material you're thinking about, and is able to do so in a way that isn't preachy or dry, and is consistent with the values of the Django community, I certainly wouldn't stand in the way of it being merged into trunk. However, the patch (or, at least, the first draft of a patch) comes first. Personally, I suspect this sort of thing would be better suited to a set of long-form blog posts. ESR's "How to ask smart questions" [1] is one example of such an approach. I have some reservations about the advice in that particular essay, but it illustrates the approach -- don't try and make this formal process or documentation for a specific project, but put it out there as a broader guide that can be read and absorbed by everyone on the internet. After all, the issues you're describing aren't Django specific - everyone would benefit from better communication. [1] http://www.catb.org/esr/faqs/smart-questions.html Yours, Russ Magee %-) -- You received this message because you are subscribed to the Google Groups "Django developers" group. To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscr...@googlegroups.com. To post to this group, send email to django-developers@googlegroups.com. Visit this group at http://groups.google.com/group/django-developers. For more options, visit https://groups.google.com/groups/opt_out.
