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 :-) Regards, Jorge -- 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.
