dictionary_switches / src / Introduction.rst


A Team Effort

This book is an experiment to see if we can combine everyone's best efforts to create something great.

You can find the contributors right before this introduction. They are listed in order of Karma Points, a system uses to keep track of contributions from everyone working on an open-source project.

In my case, I will write new material, as well as rewriting other contributions to clarify and give voice, setting up the architecture and being the Benevolent Dictator for the book. But I definitely won't be doing everything; my goal is that this is a team project and that everyone who wants to will have something useful to contribute.

We'll be using's "Blueprints" facility to add "features" to the book, so that's where you'll find the main repository of things to do.

What can you contribute? Anything as small as spelling and grammatical correctons, and as large as a whole chapter. Research into new topics and creating examples is what takes me the most time, so if you know something already or are willing to figure it out, don't worry if your writing or programming isn't perfect -- contribute it and I and the rest of the group will improve it.

You may also have talents in figuring things out. Sphinx formatting, for example, or how to produce camera-ready formatting. These are all very useful things which will not only benefit this book but also any future book built on this template (every bit of the build system for the book will be out in the open, so if you want to take what we've done here and start your own book, you can).

Of course, not everything can make it into the final print book, but things that don't fit into the main book can be moved into an "appendix book" or a "volume 2" book or something like that.

Not an Introductory Book

Although there is an introduction for programmers, this book is not intended to be introductory. There are already lots of good introductory books out there.

You can think of it as an "intermediate" or "somewhat advanced" book, but the "somewhat" modifier is very important here. Because it is not introductory, two difficult constraints are removed.

  1. In an introductory book you are forced to describe everything in lock step, never mentioning anything before it has been thoroughly introduced. That's still a good goal, but we don't have to agonize over it when it doesn't happen (just cross-reference the material).
  2. In addition, the topics are not restricted; in this book topics are chosen based on whether they are interesting and/or useful, not on whether they are introductory or not.

That said, people will still be coming to a topic without knowing about it and it will need to be introduced, as much as possible, as if they have never seen it before.

The License

Unless otherwise specified, the material in this book is published under a Creative Commons Attribution-Share Alike 3.0 license.

If you make contributions, you must own the rights to your material and be able to place them under this license. Please don't contribute something unless you are sure this is the case (read your company's employment contract -- these often specify that anything you think of or create at any time of day or night belongs to the company).

The Printed Book

Because of the creative commons license, the electronic version of the book as well as all the sources are available, can be reproduced on other web sites, etc. (again, as long as you attribute it).

You can print your own version of the book. I will be creating a printed version of the book for sale, with a nice cover and binding. Many people do like to have a print version of the book, and part of the motivation for doing a print version is to make some income off the effort I put into the book.

But buying my particular print version of the book is optional. All of the tools will be downloadable so that you can print it yourself, or send it to a copy shop and have it bound, etc. The only thing you won't get is my cover and binding.

Translations, where this project is hosted, has support for doing translations and this gave me an idea. I had just come back from speaking at the Python conference in Brazil, and was thinking about the user group there and how I might support them. (We had done a seminar while I was there in order to help pay for my trip and support the organization).

If the book can be kept in a Sphinx restructured text format that can be turned directly into camera-ready PDF (the basic form is there but it will take somebody messing about with it to get it into camera-ready layout), then the job of translation can be kept to something that could be done by user groups during sprints. The user group could then use a print-on-demand service to print the book, and get the group members to take them to local bookstores and do other kinds of promotions. The profits from the book could go to the user group (who knows, just like the Brazillian group, your group may end up using some of those profits to bring me to speak at your conference!).

If possible, I would like a royalty from these translations. To me, 5% of the cover price sounds reasonable. If the user group would like to use my cover, then they could pay this royalty. If they wanted to go their own way, it's creative commons so as long as the book is attributed that's their choice.

My Motives

Just so it's clear, I have the following motives for creating this book:

  1. Learn more about Python and contribute to the Python community, to help create more and better Python programmers.
  2. Develop more Python consulting and training clients through the publicity generated by the book (see here).
  3. Experiment with group creation of teaching materials for the book, which will benefit me in my own training (see the previous point) but will also benefit anyone choosing to use the book as a text in a course or training seminar. (See :ref:`TeachingSupport`).
  4. Generate profits by selling printed books. (But see above about the ability to print the book yourself).
  5. Help raise money for non-U.S. Python user groups via translations, from which I might gain a small percentage.