The "The reader won't know what that means" Comment

I have to admit, it's very difficult to respond to this comment. I have to fight down the urge to say things like "The Reader is not an idiot," or "At some point, we have to assume they've seen a computer before."

AFAIK there's little or no useful data data on how much background people buying technical books have.

Subjectively, it seems like folks who leave the most comments -- the noisy few -- seem to balk at chapter 1 things, write a bad review or blog post and move on. 

It appears they expect to see chapter 1 reinforce their impressions of their own skills and present the things they -- individually -- don't yet know but tend to suspect. It needs to involve minimal surprises, and no forward references to later chapters.

I wish I could write like that.

But I can't write like that. I feel the need to assume that some readers actually do know some things and want the forward references so they can skip around.

I feel the need to assume readers have seen another programming language and have worked through a tutorial or two. 

I may be wrong. It may be true that most readers buy exactly one book and expect this to be an introduction to computers, languages, and computer science. If so, I need to learn how to cater to their needs.

I may be right. People may have background in at least one language and buy multiple books. If so, I don't think "the reader won't know what that means" is really a helpful comment. 

For some technical concepts, I like to rely on inductive definitions. Rather than fussy formalisms, I think it's helpful to use concrete examples. If there are weird edge cases or seeming contradictions, a fussy definition may be helpful, but not as a starting point. The comment "the reader won't know what that means" prior to the first example is a teeth-grinding thing. Yes. They won't know. That's why the rest of the paragraph is an example so the reader will know what it means.

The good news is the reviewers are reading very closely and splitting each hair. I am eternally grateful for the opportunity to grind my teeth in exasperation. 

The Awkwardness of Fundamental Definitions

A pragmatic description of a language (like Python) from axiomatic -- or really axiom-like -- foundations is exasperatingly hard. I don't think I have any answers, but I sure do have a lot of challenges. I think there's a path that involves a lot of "don't look down -- just edge along the face of this cliff a few more feet and it's going to be okay."

The actual language foundations, and a more useful conceptual foundation don't always match up.

My specific example is trying to use a subset of Python to get started with.

One of the reasons we write software is to see useful results. So you need output, i.e., the print() function. On the other end of this, you might want to accept inputs. But. But... You could finesse that by simply assigning literal values instead of reading something. 

This leads to the print() function and expressions as a kind of minimal language to see the essence of programming. (I know this isn't an original thought. I'm setting up the conflict.)

Do we explain functions in general when we're explaining this subset of Python? Or do we stick with arithmetic? 

print("Hello, world!")

print("355/113=", 355/113)

Maybe the F-string?  Assignment? Or do we really need assignment? (Spoiler alert, no.)

What about other functions? Python has a bunch of built-ins. The math and random modules let us build small games without much intellectual overhead.

And how much can we explain about functions? The whole mathematical notion of function as mapping from domain to range: does that count? Or nah? What about Python's flexible argument and parameter handling? 

Exceptions? Do we have to explain them? Or do we shrug at division by zero and kind of ignore it? If we talk about exceptions, do we have to talk about stack frames and tracebacks?

At the foundation, a language is variable bindings and function evaluation. But. Do you explain any of that? And if so, how?

The additional complication is multiple authors, technical reviews, editors, and everyone else involved. There's a complex web of varying opinions on what's foundational and how much explanation is required. It's new to one person, so it should be up font. But, a lot of up-front material is boring. Everything in programming involves a tricky nuance somewhere; how much of that nuance is relevant now and how much is later and how much is digressive?

Trust

To an extent, there's a trust relationship between writer and reader. It may help to build this if the writer can provide a "trust me on this," scenario that (eventually) results in a more complete explanation. The logical conclusion here is that there's no place in the book for "too advanced, buy my next book." Instead, every difficult and nuanced thing would need to (eventually) be explained. That seems impossible, though.

With editors, co-authors, and reviewers, the trust relationship is exactly wrong. Everything needs to be challenged and clarified.

tl;dr Writing is sometimes hard. And that's the expectation. It's a narrow fairway surrounded by shoals. 

Super-picky Writing Advice

There are patterns to bad writing. I'll give some examples based on a blog post I was sent. It's also based -- indirectly -- on some of proposals I saw for PyCon and PyDataDC.

For the conference calls for papers, I can ask a few questions of the author, but that's about it.

For the blog post, I suggested a bunch of changes.

They balked.

Why ask for advice and then refuse to do anything?  (We can conjecture they wanted a "good job" pat on the head. They didn't want to actually have me give them a list of errors to fix.)

One of the points of contention was "Not everyone has your depth of expertise."

Sigh.

The blog post was on Ubuntu admin: something I know approximately nothing about. Let me step away from being an expert, while sticking closely with being able to write. I work with editors who -- similarly -- can write without being deep technology experts. I'm trying to learn what and how they do it.

In this case, my editing was based on general patterns of weak writing.

1. Contradictions
2. Redundancy.
3. Waffling.
4. Special-Casing.

Any blog post on Ubuntu admin that starts with "This is not just another blog post..." has started off with a flat-out contradiction. It emphatically is another blog post. You can't rise above the background noise of blog posts by writing a blog post that claims it's not a blog post. Sheesh. Find a better hook.

Any blog post on Ubuntu admin that includes "This blog post assumes the reader is familiar with linux sys administration." As if -- somehow -- a reader interested in Ubuntu admin could be confused by the required skills. It's clearly redundant. Cut it.

(This led to an immense back-and-forth with repeated insistence that *somehow* someone once got confused and *something* bad happened to someone. Once. My response was adamant. "It's redundant. The title says Ubuntu. That covered it. More repetition is an insult to the reader.")

Anything that has "this may nor may not work depending on your filesystem" is flat-out confusing: it covers both bases. Does it work or does it not work? Which is it? Clearly, there's some kind of precondition -- "must be this file system" or "most not be this file system" -- buried under "may or may not work." It's not that I know anything about Ubuntu file systems. But I can spot waffling.

Indeed, when you look at it, this is a "hook" to make the blog post useful and interesting. Some advice doesn't work. This advice always works. Simple statements of fact are better than contradictions and waffling.

Finally, there was a cautionary note that replacing "/swapfile" with "/ swapfile" would brick your OS. Which. Was. Crazy. It's really difficult to arbitrarily introduce spaces into shell commands and still have proper syntax. Sometimes a shell command with rando spaces may have proper syntax and may work. Most commands won't work at all with a rando space added. Try some and see.

What's more important is only one random punctuation error was listed. The special-case nature of this was a tip-off that something was not right with this advice.

What about a random ">" in the command? Or a random "|"? Not covered. A single space was considered worthy of mention. The rest. Meh.

(If you want details, it's was `dd -of=/swapfile ...`. If asked, I'd guess `dd -of=/ swapfile` is a syntax error because `swapfile` isn't a valid operand to `dd`. Not an expert. I didn't check. AFAIK, the author didn't actually check, either.)

None of this editing was based on any vast expertise. It was simple editorial work looking for some common problems with hasty writing.

1. Avoid clear contractions.
2. Avoid redundancy.
3. Don't waffle.
4. Special cases are instances of a more general pattern. The pattern is more important than the case.

One of the contentious back-and-forth issues was "I'm not writing a book, it's only a blog post."

Wait. What? Blog posts are often more widely-read than books. Look at Stack Overflow. If one of my books had the kind of readership my Stack Overflow answers have, I'd be living on royalty payments alone.

A blog post requires the same depth of care as a book.

This applies to proposed talks at conferences, also. The proposal needs to be carefully edited to reflect the final presentation's care and quality.

Thank goodness, most of the 100's of proposals I've looked at rarely have the four obvious problems listed above.

The problems I see in conference proposals are minor.

1. Incompleteness. A 45 minute talk boiled down to 4 bullet points doesn't give us any confidence. It's hard to imagine filling the whole time with useful content when looking at a four-sentence outline. Will it be rambling digressions? Or will we have disgruntled attendees who had hoped for more?
2. Weirdly cute style. Things like "This is where I jokingly outline something something and the real fun begins." We assume everyone is witty and charming, you don't need to tell us. We assume all talks will be fun. Can we move on to the Python (or PyData) topics you'll cover?
3. Sales Pitches. "[Speaker's name] is a respected industry expert who delivers exciting and transformative keynote addresses and will dynamically cover the state-of-the-art blah blah blah..." Please. What Python topic is this? We like to review the outlines without speaker information; we need to focus on the content. Subverting this by including the speaker's name in the description or outline is irritating.

I'm really pleased we see very few PyCon Code-of-Conduct problems in the calls for proposals. That is a delight.

Editing is hard work. I'm sorry to report that editing means making changes. If you ask for editorial advice, it helps to listen.

Writing Tools

Read this: http://thesweetsetup.com/apps/our-favorite-pro-writing-app-for-mac/

What I have been doing instead of using these sophisticated, integrated writing tools?

I use OmniOutliner. https://www.omnigroup.com/omnioutliner I've used it for years. It does a lot of things. Most notably, I can create multiple columns so that I can create page budgets for outlines. Acquisition Editors like this. Except, of course, they like it as an DOCX file, which requires a bit of manual juggling to produce.

I use BBEdit and KomodoEdit for a the bulk of my writing. http://www.barebones.com/products/bbedit/index.html
https://www.activestate.com/komodo-ide/downloads/edit

"But wait," you say, "those are text editors."

(Or, more dismissively, "there are merely text editors.")

Correct.  I use RST markup and write in Unicode text.  I use tools to convert the RST text to a variety of other binary formats. See http://docutils.sourceforge.net/docs/user/tools.html for a list of tools. This is what I often use:

• rst2odt creates ODT files which can be then converted to DOCX.
• rst2html creates web pages.
• rst2epub creates ePub files. From there, Kindlegen can convert to Kindle-unique format. https://www.amazon.com/gp/feature.html?docId=1000765211 

How is this better than a tool like Scrivener? It depends -- as always -- on what you're trying to optimize. My pipeline has the (dubious) advantage of being very inexpensive. Except for OmniOutliner and BBEdit, it's all community-edition, free software. If cheap is your goal, I've got cheap.

The cool part is this.

The Mac OS X desktop is an integrated writing environment. I have browser, outliner, writing tool, publishing tool, etc., etc., all readily and immediately available. The "look and feel" isn't consistent, but I'm not sure that's a show-stopper.

The biggest difficulty?

BBEdit doesn't enable the Mac OS X grammar checker. Really. It's switched off. The grammar checker is sometimes handy for preventing a large number of common, dumb writing mistakes. BBEdit shows the word count, which is very helpful for some kinds of writing. I wind up using a second app (i.e. the built-in Mac OS X TextEdit) to make a grammar check pass.

I think, however, the hacker-friendly free-and-open-source tool chain may have reached the end of its service life.

Why Not Use Word?

"After all," you say, "MS-Word does everything."

Agreed. It does everything badly and confusingly. (1) The outliner is hard to use and is firmly tied to the text in a way that breaks outlines all the time. (What's that paragraph doing there? Why is it the wrong outline level?) (2) There are too many useless features. The presence of "advanced" mode is a UX nightmare come true. (3) The character-mode and paragraph-mode formatting rules are baffling (and break the outlining.) (4) The styles are essentially invisible: you have to click on the text and check the style side-bar to be sure that the (invisible) markup is actually right.

The worst thing is that publishers have house style sheets for MS-Word that drive the publishing pipeline. This means that writing involves a weird step where I have to apply the publishers styles to things that are **very** clearly annotated with RST markup. You have to review each word. The words may look right, but have the wrong style applied. This is extremely tiresome to get right.

I intend to stick with plain-text markup. Scrivener supports MultiMarkdown. It's not RST, but it seems to be as rich with built-in semantic categories.

The Lynda.com Experience

One word: "wow"

More words: "Helping shy people get up and do what needs to be done."

Yes, that's Garrison Keillor's tag line for one of the "sponsors" of "A Prairie Home Companion": the Powdermilk Biscuits company.  (Heavens. they're tasty and expeditious.)

The folks at Lynda are truly great at shepherding folks through the process of preparing and recording their material.

Recording is hard. The point is to say each thing perfectly. But, the things have to fit into a larger narrative of a section that fits into the larger sequence of chapters that makes up the course.'

Giving essentially the same content in a presentation at a conference is almost unrelated. Talking at a conference has a live audience. It's one-time-only, and you can ad-lib.

Doing this takes patience. And skilled editing both at a content level and at a technical level. Lynda has it all.

The thing that made me the most comfortable was having my presentation material ready. Each section is a 5-minute lightning talk. I was had all of my slides ready. I'd been through them enough times to be sure that I could handle the 5-minute format. And when there are editorial changes, they tended to be relatively minor.

I may try it again. It's a lot of work. Certainly more work than writing a chapter in a book. A chapter can go deep. A presentation has to stick to the high points: this means that the supporting depth must be there, but you're not going to wallow around in it. Essentially, you're making the "elevator pitch" for each one of your points.

The recording and live action studio space were fun. I've never been recorded or taped like that before. They eased me into it, coached me through it, and made sure all of the content was there in a way that could be edited into a high quality final product.