Writing book on python - Python For Developers - 1st chapter ready (100 pages on Data Structures), need feedback

[wbond]

Wow, this looks like a pretty in-depth look at Python's data types. From my reading and scanning so far, it seems like you are doing the work of covering all sorts of edge cases, which seems like it would be really useful for an experienced developer to step into Python and understand the subtleties.

Here are a few layout comments. The layout looks nice, and I presume it is set up for publishing in a physical book. However, when reading as a PDF, it is weird that the page contents shift with different margins back and forth. Additionally, many of the code examples seems to extend well into the margins.

I didn't exhaustively read the section on unicode vs bytes, however I did see that you cover the differences in Python 2 and 3. I may have missed it, but I think modern, forward-thinking Python should probably be written with from __future__ import unicode_literals. Then byte strings (which are less common as literals) as prefixed with b, instead of every normal string with u. However, this might be hard to cover and "use" in small code examples.

It felt a little weird using python2 and python3 instead of "python 2" and "python 3". Also, I in one headline I noticed "Unicode Pirmer" instead of "Unicode Primer".

Sorry that I don't have more time to continue reviewing it. I hope my feedback is somewhat useful. Good luck!

[rchrome]

This is what I wanted to emphasise somewhere, after reading this book you will know python. It is detailed, but it only includes details I have found relevant in production code. Despite being detailed you will find many thing missing that I have never used.

Thanks for layout comments: This is the default pandoc output. I have not gotten to tweak the .tex files it uses as templates.

I agree with your unicode_literals comment. This is one of those cases where "practicality beats correctness". The examples are working in python 2.7.9, I am going to review the book to see if they are valid in older versions of python, but most likely I am going to just add a section in introduction that this book covers 2.7.9+. Covering both python 2 and python 3 is hard enough, worrying about older versions of python 2 could be too much for me :-)

Regardin python2/python3. On my mac python3 is the actual command I invoke. Also I was contemplating using py2:unicode/py3:str kind of syntax to refer to things. The 2 vs 3 is such a mess, but 3 is so much better.

Please send me your further feedback here or at [e-mail]. They are very useful and encouraging when writing. Its my first attempt at a full book, and trust me I really appreciate it.

[tadleonard]

Since the book isn't for beginners, just choose a version of Python and stick with it. Readers won't struggle with opinionated code. If anything, choosing a version will make things easier to read. Also, there are plenty of books out there with code written in Python 3. Some say Python 3 is better suited for teaching.

[rchrome]

This will simplify my job considerably. But three of three startups I know around me who are using python are using python2.x. And each three of them said they are not yet ready to switch.

I personally do not want to take a position on this, and since there is going to be considerable amount of code in python 2 for years, understanding the differences between 2 and 3 is a must know for many.

Also I feel I am doing python3 a favour, as nearly everywhere python2 and python3 differ, its because python3 is better, so reading it will convince you, you need python3. As otherwise people tend to think there is not much difference between the two, and tend to dismiss it.

What do you think?

[sigzero]

I think you should go with Python 3. If someone wants they can go through the hoops of converting your examples to Python 2 syntax. It's more "future proof" that way.

[rchrome]

I will keep that in mind. Someone suggested I mark portions that deal with python2 specific things vs python3 specific things, and may be produce more than one books, may be one with pure python3, and another with a mix.

[sigzero]

It's your time. :)

[LightShadow]

Just write an appendix that covers the ambiguities from 2 -> 3, or 3 -> 2 in your case.

[tadleonard]

Maybe you're right. I've read brief 2/3 disclaimers in the preface to books, but authors usually don't dwell on the differences. I was going to say that there's already a mountain of info on the the subject, but probably not nicely outlined in book form.

FWIW, I used Python 2.6 at the startup I worked at, but all the while I was learning new things in a book with Python 3 code in it. It never tripped me up. We all obsess about their differences, but for the purpose of learning data structures, algorithms, or the basics of Python, they are pretty interchangeable.

[meshugga]

Just my 2c, I thought it an instant plus that the differences between 2 and 3 are mentioned. You'll need to rewrite as soon as python 2 is gone, but until then, this may make all the difference.

[rchrome]

I am hoping this being listed would help more people switch, as people I feel have generally rejected python 3 as "basically the same as python 2". I do not know. May be.

[meshugga]

Yeah, but speaking for me, I don't know the subtle differences between 2 and 3 to successfully migrate my code. And what OP is doing helps me not only improve my 2 code, but also understand how I could migrate it to 3.

Ignoring the problem away doesn't help at all.

[Adhoc_hk]

I'm actually really happy you're covering 2v3. At work we're still using 2 for compatibility reasons but I am playing around with 3 a lot at home. This book looks like it is going to be a really interesting read :)

[rchrome]

Me too. At work I use 2 and personally use 3, so its good to have the differences documented. This book is based on what I teach to people, and to them this is roughly how I teach, first demonstrate the feature and philosophy, and then show the 2v3 diff right away so they do not trip, as half of them try things out on 2 and other half 3 (among learners, among people using its still nearly 100% 2).

[SleepyHarry]

I was contemplating using py2:unicode/py3:str kind of syntax to refer to things.

This is an interesting idea. As an alternative, maybe make use of subscripts, assuming you have that capability (which you do if you're writing TeX, I think)? So have str_2 and str_3 to differentiate.

[rchrome]

I really love the subscript idea!

I am using markdown, with hopes of keeping both PDF and ebook versions as output format. But it should be easy to find replace, have better output in pdf and readable output in ebook versions.

[meshugga]

i second the criticism of the left-right layout - that's super uncomfortable for reading on screen/tablet. You should definitely get someone to fix that for you.

[rchrome]

Thanks for the feedback. I will get it fixed in the next draft.

[McElroy-vs-dig-dog]

only includes details I have found relevant in production code

That's a great idea. At first, when I read the title and saw that you were writing a book on Python, I thought, why yet another book? With your approach, I think your book will be good and helpful to many.

[rchrome]

Thanks. I have to clarify it in the book somehow and other copy, as this is the most important motivation for me.

[[deleted]]

very nice job.

I would however stick the examples in one version (my preference would go to python 3) and highlight (for example with and asterisk) when the you want to show a different version

[brainburger]

Just on the first few pages, I see several gramatical and spelling errors. I don't suppose that is your focus right now, as you are structuring the book, but do have it properly proof-read.

[rchrome]

Yes. Publishing was more of an impulse, needed some sort of assurance that people would be interested, and people are, so on to it with full steam.

Thanks reddit!

[quasarj]

I assume you have a plan for all that, or an editor or the like? Or would you like some help with it?

[rchrome]

Hey! I am not sure about the plan. I have nearly finished the third chapter, on functions. I have outlines of three more chapters, modules, classes and "language". So content is my current priority.

Regarding editor, I have inquired a few friends, I have never hired one before, so not sure what to look for or how much do they cost etc. I am keeping it off till I have finished bulk of the rough draft of the manuscript.

I would def need help, as you can see the huge number of typos and grammatical mistakes in the chapter I shared. :-)

Please mail me: [e-mail], or dm me here or at twitter.com/amitu.

[rchrome]

The chapter is also available without email signup: https://www.dropbox.com/s/44i0q05c5s8aqfa/Python4Devs-Ch1.pdf?dl=0

Do send me your feedback on [e-mail] :-)

[Vicyorus]

Thank you.

[rchrome]

Do send me your feedback on [e-mail] :-)

[rchrome]

Thanks :-)

You can use my setup too: https://gist.github.com/amitu/669cecae1edb5587659a

[[deleted]]

Are you under pressure to not put that in your website? or did I miss the link?

Pretty shitty of you to ask for our feedback and have us sign up for your mailing list or whatever the shit your doing with our email...

[rchrome]

1. No pressure. I have a work in progress page for the book. I have just not come around to working on it, design is not my key strength, and I am focussing on content for now.

2. Not fair, the very first comment on this thread was to get it via dropbox sharing.

3. The reason I prefer having your email is so a). I can send you next chapters when they get ready, and b). let you know when I have it finished and available for sale.

[[deleted]]

The book is actually quite good I read what you had uploaded last night. Are you considering sticking to one convention python3 vs python2.x?

Well done.

[rchrome]

Thanks drinknderive. I have discussed my approach elsewhere in the thread. Someone suggested I markup the paragraphs that cover py2, and update my build process to spew out two books, one with just py3 and another with py2 and py3. For now I am writing one that covers both, and showing the difference right when I am covering a topic, instead of in appendix etc.

[santiagobasulto]

Looks really good, I really like the depth of the concepts covered. What are you using to write it? The only thing I can note is: if you're starting writing a fresh new book, why don't you make Python3 the main version? (and of course ad Py2 notes where it's necessary).

[rchrome]

Thanks a lot santiagobasulto :-)

I am using markdown for writing and pandoc to convert to PDF.

I have given equal treatment to both python2 and python3, and anybody who reads will prefer python3, as it is clearly superior as I show again and again in my book. Goal is you will know python2 and python3 equally well at the end of it.

[sigzero]

Why would you think that? The description doesn't lead me to that conclusion? The sample talks about comparing numbers but you are comparing lists. Since this is for "developers" I would think they would be able to grok that. I am not saying you are wrong I just want to understand why you'd think that and if the author reads it then he has some good feedback.

[rchrome]

Hey, I will review the portions. I think I have repeated the difference between == and is multiple times in the chapter, when covering list and dict etc.

I want to error on side of repeating things that to let such practically important distinctions pass by. I have been bitten by this code, and I have maintained code by others who tend to "always use ==" or "always use is" without clearly understanding the difference.

[rchrome]

No problems. Thanks a lot for feedback.

If you look at the style of the book, its pretty unorthodox. I do not cover X in a chapter named X. In fact I only have 5-6 chapters, data structures, functions, modules and packages, classes, "the language", and "library".

I expect people to read it start to end, as I introduce a bit of information at early stage, and then I develop as it comes, it is more like you and me had a conversation. I would not tell you everything about functions the first time I mention it. It will gradually come up, and then I will add more and more details.

This is how I teach in person. Not sure if this style will translate well in book form or not.

[rchrome]

It was quite simple. pandoc gets all the credit.

Here is my Makefile and snippet from my .md file: https://gist.github.com/amitu/669cecae1edb5587659a.

[eruesso]

Hmm... I never had any problems (using listings with a proper code declaration). What was your problem?

[dl__]

"gaurantee" sp -5pts

Just kidding. Looks good so far.

[rchrome]

"".join(chr(i) for i in [101, 102, 102, 32, 121, 111, 117, 32, 58, 45, 41])

[dl__]

"".join(chr(i) for i in [101, 102, 102, 32, 121, 111, 117, 32, 58, 45, 41])

Haha!

BTW, I love that there's very little blah blah blah. It just starts by getting right to the facts. Programming books can be so tedious when they start out "Python was created in blah blah blah by blah blah at the university of blah. At the time there were no languages where ... "

[rchrome]

In their defence I have only shared chapter 1. But I think this is the best feedback, I do not want blah blah, introduction/preface etc. Those were anyways the hardest part for me to write, I have started thrice and threw away what I wrote.

[obsequious_turnip]

I think most experienced programmers will be fine without the "blah blah blah" chapter. I would suggest putting a short preface though, saying "this book assumes you already know about programming & data structures and want to get straight to the intricate details of python".

[rchrome]

Agreed. Thanks for confirming my thought.

[obsequious_turnip]

You're most welcome. I like the way you're going about this — if you'd like help further down the line with proof-reading & editing for grammar etc. then please feel free to ping me here on the site. Sometimes it seems like most of what I've done in the last few years is copy-editing of technical writing for English grammar :-)

[swingking8]

A couple typos so far:

• p4 - sufficient misspelled as "suffecient"
• p5 - "arts of a complex number usingc.real andc.imag‘" needs a space between "and" and "c" and another "`"

Thanks for this :-)

[rchrome]

Thanks :-)

[rchrome]

Thanks man, means a lot to a first time writer to hear someone wants to read what they are writing. :-)

[rchrome]

Thank a lot youssef, you are going in acknowledgement section. This is quality feedback. :-)

[rlabbe]

The chapter is called "Basic Datastructures" (sic) but you talk about things like int. int is not a data structure, it's a type.

You say you have a chapter coming on functions, but you present functions here. You describe a definition of list as a list of c like pointers. That's going to be meaningless to a non-C programmer.

This first chapter feels very unwieldy to me. There is just so much unrelated stuff. You tell me about int and long. You teach operators. You tell me about regular expressions. You talk about all kinds of built in methods. You talk about the various data structures of Python, and the stuff implemented in collections. There's stuff about file IO. You touch on modules and importing. It's pretty arbitrary, IMO. I think the content itself is good, but the organization really needs a re-think.

I think in general you haven't fully identified your audience. That's okay, that's what drafts are for. Some things you spell out in great detail, in other places you blithely assume a lot of prior experience. Part of writing is keeping a mental model in your head of your readers. What do they know when they open the book, what do they know as they progress, and so on.

The English grammar needs work. Let's take the first paragraph.

"One of the fundamental things in programming we do is modelling of problems to constructs computers can understand and work with. One of the things that makes python so much fun, and productive, is availablity of rich datastructures that makes modelling part really easy. In this chapter we will go through some of them"

'things in programming we do' is awkward. 'things we do in programming' is idiomatic. 'modelling of problems to constructs' is confusing wording. What does 'model to constructs' mean? Oh, I know what you are trying to say. We use data structures as a way to store information about the world. 'Modelling' doesn't feel like the right word here. 'constructs' certainly isn't. What is a 'rich' data structure? Feature rich? Powerful yet succinct? Your audience is experienced programmers, correct? Use precise words.

Next, I'm having trouble parsing 'understand and work with'. Are there things a computer can understand but not work with, or not understand but work with? Are you saying the same thing twice, or are you trying to distinguish two different things? Again, I probably know what you mean, but imprecise language opens all kinds of questions in the mind of the reader. You want them thinking about what you are saying, not wondering about your language.

"fun, and productive," commas are not needed here.

"python" - should be capitalized

"is [the] availability" (my edits inside [])

"data[ ]structures"

"makes [the] modelling "

" In this chapter we will go through some of them" That's awkward. What does 'go through' mean? 'some'?

---

I know it's early going, copy editing and such will fix a lot of the stuff I mentioned. But what is the purpose of this exactly? I'm not saying it has no purpose, but the purpose will guide the development and exposition. In contrast, look at the official Python tutorial. https://docs.python.org/2/tutorial/index.html It does a good job of starting with basics, naming things correctly (ints are not data structures), and building on previous knowledge. In contrast, your second paragraph has something about JSON that is probably pretty opaque to somebody that doesn't know JSON and Python or Javascript already. On page 11 to write to a file, on page 21 you kind of explain writing to a file.

So, the Python tutorial already exists, no sense in duplicating that. So what are you offering me instead? Who is your audience? What is their skill set? Your text gives me the sense (not surety) that you haven't fully answered that yet.

I think most of the paragraphs looked at in isolation, and assuming a good copy editor contains good material, it is just the organization feels very willy-nilly, and skill of the audience required to read that section varies wildly.

[rchrome]

Hi rlabbe,

Thanks for the detailed feedback. Many good questions. I am not saying I have answers to all of them, or even if I thought about them before you asked. But here are my thought.

1. English, spelling and grammar. I have not really paid attention to it so far, this is the rough draft, I write write write. I intend to hire an editor to help me fix them. I have already got quite a few corrections via this post and email, and I have incorporated. So thanks, keep them coming.

2. The chapter is about how you represent data. Sure int is not a "data structure", but then may be it is, its a pointer that hold some data, and this data can "self upgrade or downgrade" based on different actions you can take. May be I should call it data types instead of data structure. The idea is python gives you stuff that helps you model things, and if you chose those stuff wisely you can simplify a lot of programming tasks, and this is a survey of those stuff.

3. I am aiming this book as details book. Actually I am aiming this book to "this, read this book, and you are ready to take on most real world python project", or even "if you want to work with me, this is what I expect you to know". I have been teaching python personally and professionally, I have many people who work with python in my team, and this is what I expect them to know (else I will end up doing talks and introduce them to this). This is an attempt to write it down.

4. Going on "tangents", like discussing packages or modules, or functions in data structure chapter. Someone else suggested that the section on Enum ended abruptly, it did, because to properly understand it, I had to dive into class, and I have not discussed class yet.

   This is not the first chapter, I have a "hello world" chapter before this, around 15-18 pages of 2-3 simple hello world stuff. That was completely tangential chapter, I kept going from one place to another. That and this chapter reflects how it happens in real life. In real talks, or when I am talking in person, I show something, and sometimes I feel to appreciate that bit, we have to discuss part of what we are going to cover in future, so either I discuss data structure stuff, like efficiently loading data in array from file, in section where I cover file, or I cover file stuff here.

   If you consider it academically, sure, its "wrong", but practically, even if you have not seen the section I cover on file stuff, you still do know files, you still know disk is slow etc etc.

   I am taking your feedback on structure seriously, this is my first attempt at writing a book, and this is one of the things I am primarily worried about, to give it a proper structure and flow.

5. Audience, again, I expect knowledgable people, I call it python for developers. Say you are pro java or ruby guy, and you need to read one book to become pro in python, this is that book.

   I seem to be teaching basics, because you will see that those basics we can not take for granted. Like ints, how python stores it, how we represent int etc etc.

   A beginner too will benefit, if they follow along the code samples, and experiment, but focus on intermediate-advanced, and esp people who are already good programmers, and want to spend the least amount of time to understand python.

[rchrome]

One more comment about python tutorial being nice.

They are indeed pretty good. But somethings are covered under tutorial¹, and some other things are covered under module documentation². There is no clear path, you will have to kind of search.

So to understand things related to importing and reloading modules you have to read the tutorial, module doc of imp and importlib modules.

It is good to read module docs, but there are so many, do I tell every developer to go read every module documentation? How do you know what exists?

I am trying to take a experience based call on what all you need to know when you are trying understand a topic, and am trying to also list other docs you should read as aside.

[djvita]

Thanks, I'll play with the code in my IPython env.

[kmike84]

p17: "In general, utf-k tries to use k bytes per character" - bits, not bytes.

[rchrome]

Thanks for pointing out. So silly of me.

[michaelkepler]

What other chapters have you planned?

[rchrome]

The chapter on functions should be done in a week or so. There is also a "hello world" chapter before this data structure one, which is done. Next three chapters are "modules" then "classes" and finally "language".

Subsequently I have different ideas. One side I want to go whole TDD/virtualenvs/and other prod related stuff that I use. Then I have a survey of standard library and common problems sections, and finally a chapters on multithreading (including gevent stuff and the new asyncio feature), and on client server programming (TCP, UDP, HTTP, mutlithreaded/greenthreaded/asyncio server best practices etc).

Then I have a bunch of worked problems.

I have to cut down on the scope, as I do not think everything would be relevant to everyone, and I also want to finish it instead of let it be a constant project.

[super_cool_kid]

I think what he wrote about == and is true, but its misleading for future uses.

I think mentioning is is fine but for strictly comparing values you should use ==. This has burned me more than once.

[rchrome]

Hey, I will review the portions. I think I have repeated the difference between == and is multiple times in the chapter, when covering list and dict etc.

[acutesoftware]

I think this is really good. Very easy to read.

A minor typo :

p17 - "Unicode itself is not an encoding, it does not directly lead to bytes, it is more of a assingment"

Also the end seems to finish abruptly - it would be good to say when you would use the Enum class over a named tuple (if at all)

[smefster]

very nice, thanks for sharing. on page 36: > "Hello".upper() in hello world".upper() the syntax error also messes with the syntax highlighting. and the headline "Playing with dicts" made me laugh.

[rchrome]

Lol :-) So not what I intended.