Stoyan Stefanov

Personal blog

 

Archive for the "books" Category

O’Reilly sales data summing

Wednesday, January 4th, 2017

Hello fellow O'Reilly author, and congrats on finishing your book, I know it wasn't easy! 🙂

(If the above means nothing to you, my dear reader, move on, shut down the computer and maybe go outside)

Believe it or not, the O'Reilly site has a page that shows your sales data. Pretty graphs too. What it doesn't have is the total of how many books you've sold in all of the time.

Worry not my sisters and my brothers.

Pop up the console, type data and see what happens - the data that powers the graphics is there. As many titles you have, as many data!@#$% variables pop up from your browser console's autocomplete. In my case - 4 books, 4 datas.

data

Exploring the data...

explore

As you see - two arrays: digital and print data. X is timestamp, Y is number of books sold. All you do is sum up all Y values.

Except there are duplicates in the data. So making sure that only one Y is counted for each X timestamp does the trick.

And here's a little something I came up with, feel free to improve:

var map = {}; // to de-dup
data57350[0] // digital sales for React: Up and Running
  .values // it's all there
  .filter(v => v.x in map ? false : map[v.x] = 1) // rm dupes
  .reduce((prev, next) => prev + next.y, 0) // totals

One liner so you can paste....

var map = {}; data57350[0].values.filter(v => v.x in map ? false : map[v.x] = 1).reduce((prev, next) => prev + next.y, 0)

Now change [0] to [1] for the print data. When change the data*XYZ*.

Not the whole story

Keep in mind:

  1. What it says right there on the site: "Please Note: This data is from major retailers including Amazon, Barnes and Noble, and oreilly.com. Royalties are not calculated on the basis of these sales."
  2. Also the data goes only 2 years back (see the graphs)

Better way/whole picture?

There must be a better way. I just don't know it. Oh wait, I can ask somebody at O'Reilly 🙂

Take care now, bye-bye then!

(Now go back to working on your next title, you slacker, you!)

Dear technical copyeditors,

Sunday, September 8th, 2013

We need to talk.

Background

I'm a technical author. I write books about programming. I don't speak or write proper English. Not my area of expertise. I need your help. But, please, don't overdo it. Here are some Do's and Don'ts that will make our life together easier.

DON'T use Word

Stop it. I know it's not your fault but try to change this within your organization. Technical people are lucky to have discovered the beauty of source control. You know, Git, SVN, that sort of thing. Technical books should be written like programs, using plain text (asciidoc, markdown). From there you can generate epub, mobi, pdf, html whatever (lookup "pandoc"). If you're not familiar, source control is like "track changes ON" in Word, only infinitely better.

DO track your changes

Giving me a word doc changed beyond recognition with no way to quickly see your changes and no way to quickly undo what you messed up is criminal.

DO help me make my prose shorter

Delete, delete, delete! (with track changes ON, of course)

DON'T add verbiage to my prose

See above.

When I see changes like these, I want to chew my leg off and run away from the project:

ME: A number of events reshaped the web development landscape in a positive way: [list of stuff]
YOU: A number of events reshaped the web development landscape in a positive way. Some of them are given as follows: [list of stuff]

"As follows"? Search and delete all your "as follows". We can all see it follows.

ME: The cat has certain characteristics (color, name, weight) and can perform some actions (meow, sleep, hide, escape).
YOU: The cat has certain characteristics (color, name, weight, and so on) and can perform some actions (meow, sleep, hide, escape, and so on).

The golden rule: remove, do not add to the text.

DON'T remove my emphases

I use italics when I try to emphasize. This is because I can't make sense of your multiple custom formatting styles (italics, emphasis, bold, keyword, term) in your custom .dot templates. But you know your custom styles. Use the right one. Don't just remove my formatting and de-emphasize the text. It dies a boring death!

ME:
A regular expression consists of:

  • A pattern you use to match text
  • Zero or more modifiers (also called flags) that provide more instructions on how the pattern should be used

YOU:
A regular expression consists of:

  • A pattern you use to match text
  • Zero or more modifiers (also called flags) that provide more instructions on how the pattern should be used

DON't capitalize my "boolean"

Word auto-correct does it. Ditch Word. New words get special treatment initially. Then they integrate into the common language. E.g. "Web Sites" -> "web sites" -> "websites". The word "boolean" is common in programming.

ME: "numbers, strings and booleans"
YOU: "numbers, strings and Booleans"

Yuck!

DON'T just "fix" stuff

Don't reword my prose. If something's sounds off, tell me in a comment. Ask clarification. Suggest a better wording. Don't just fix it.

Otherwise we end up with nonsensical gems like:

ME:
The regular expression objects have the following properties:

  • global: [...snip...]
  • ignoreCase: Whether the match is case sensitive or not, defaults to false.
  • multiline: Search matches that may span over more than one line, 
defaults to false.

YOU:
The regular expression objects have the following properties:

  • global: [...snip...]
  • ignoreCase: When the match is case insensitive, the defaults to false.
  • multiline: Search matches that may span over more than one line default to false.

Rule #1 in technical writing: above all, be technically correct!

DO let me be human

I have some way of saying things. Many people seem to like it. Let me sound like me. Even if it's not the proper Queen's English.

ME: The function F contains the variable b
YOU: The F function contains the b variable

Err, no!

Less is more

Thank you for your understanding!

In conclusion, the top 3 tips for our happy relationship: are given as follows:

  1. Fix my punctuation, I know I suck at it
  2. Suggest lots of deletions to help make the prose compact (we all suffer from wordiness)
  3. Comment on my nonsense, don't fix

Technical writing checklist

Tuesday, March 5th, 2013

update: added "can", "in order to"

Working on a first draft should be quick and dirty. Then comes editing. And at the last stage, right before you're ready to send the finished manuscript, how about a checklist? A lint, if you will.

Starting the OOJS second edition I took note of my common mistakes. I came up with (and kept expanding) a checklist of last minute sanity checks that I go through before sending each chapter to the editor. Just when I think I'm ready I search for each string in the document and address potential issues.

The big picture items:

  1. Technical writing should be precise and correct above all else. Weak and ambiguous words such as "may" or "some" must go
  2. Cutting out filler words
  3. Avoiding common mistakes, e.g. "its" vs "it's"

Here's my checklist with my common mistakes. Feel free to customize for your own writing.

JSLint

Since I'm writing about JavaScript, JSLint (or JSHint) are constant companions. Consistency (semi-colons, spacing) helps the reader focus on important things. Plus, sloppiness in any form has no place in technical writing.

"very"

Filler word. Delete.

"basically"

Delete.

"actually"

Most likely not needed.

"pretty"

Doesn't help the prose, delete.

"easy"

Don't say it's easy, show and prove how easy it is.

"useful", "interesting"

Same as above. Prove it. Why is it interesting? When exactly is it useful? It's not enough to be useful just in general, because anything can be useful eventually.

"its" vs. "it's"

Common mistake. Go through and make sure it's the intended use.

"than" vs. "then"

Same thing. Search the chapter for each instance and read the sentence once again.

Shorten "it is", "you are", "you will"

This is my British publisher's issue I think. As far as I remember they changed all of these. No need. These are longer and make you sound pompous.

"way to"

Can often be removed

"we", "our"

It's all about the reader. The word is "you".

"I" can be used but sparingly. Say, 3 times in a book.

"We" sounds like "me and the crown" (this is from Packt's guidelines)

Arguments vs. parameters

Commonly mixed. It's good to be precise. Wikipedia.

function sum(a, b) {
  return a + b;
}

var price = 100, tax = 20;
sum(price, tax);

 

price and tax are arguments passed to the function sum(). And a and b are the (formal) parameters that the function sum() accepts.

"some"

Which? It's hand-wavy.

Searching for "some" also matches "sometimes", which is no good either.

"will"

(Got this from Steve Souders' reviews of calendar articles.)

Stuff is happening now. It's here and it's concrete. "will" makes it sound like it may not happen.

"The result will be..." -> "The result is..."

"may", "might"

May or may not? Weak. Ambiguous. Gone.

"probably"

Hello, technical topic here. It is or it isn't. No wiggle room.

AJAX -> Ajax

Way past the initial excitement.

"jQuery", "YUI"...

Avoiding references to current topics and events in a feeble attempt to write "evergreen" books (as if it's even possible for a computer book). Any time-sensitive info comes with "at the time of writing" disclaimer.

"can"

"Can" is weak. Doesn't mean anything. Of course you can.

"you can use" -> "you use"
"can be" -> "is"

"In order to"

Filler. Shoot at sight.

"in order to" -> "to"

Update: http://matt.might.net/articles/shell-scripts-for-passive-voice-weasel-words-duplicates/

AsciiDoc

Friday, June 8th, 2012

When in phase #2 of any writing process (the typing phase) you need minimal distractions. You need to just type away as frictionlessly as possible and lose no time at all in anything other than typing.

That's why MS Word (or any word processor really) is poorly suited for real typing, as oddly as this sounds. There's just too much UI going on, menus, options, toolbars. Even if you ignore and manage to hide these, it will causes damage with auto-correct and smart quotes in your code examples and so on. You don't need any of that. You don't even need to see that there's an option to make something bold or italics. Because that will make you think. Should I make this bold? Or maybe italics? All this takes your energy and causes you to type less.

Word is also terrible for writing code. It's simply not a code editor.

The best software for writing a computer book is simply your favorite code editor. It has everything you need, and everything you're used to. Tabs vs. 2 or 4 spaces and so on. Auto-complete. Your favorite macros and shortcuts that you normally use every day.

Your book is best written as plain text, as close to normal source code as possible.

Plain text

When I started typing away on JS4PHP, I just used TextMate which is what I use for coding anyway. I just wrote text. I thought of writing HTML initially and then use something to convert it but quickly reconsidered. Typing <code>var a = 1;</code> is too much typing. Opening and closing tags - meh.

The cool part about TextMate is that that is has auto-complete based on what you've typed already. So I got accustomed to write Ja, hit ESC and watch it complete to JavaScript

Knowing that there will be editing I figured the sloppier the original, the more rigorous the editing, so I just didn't bother to format almost at all. I couldn't help myself putting some ` though as in Here the function `foo()` is .... when dealing with code inline if a paragraph. Or some *really* and this is called a _closure_. You know, little markup pieces.

Once the first ugly draft was done, I started looking at how to convert this plaintext into something O'Reilly can use. I have heard of something called docbook or bookxml or something similar and suspected that O'Reilly supports it. So I though I have to take my plaintext and make it XML. But much to my surprise I learned that O'Reilly supports AsciiDoc.

AsciiDoc

AsciiDoc is an open source project that lets you write plain text with minimal markup and then generate a bunch of different outputs from the source.

For example `inline code` and *bold* and _italics_ and then some highlighted source code:

[source,js]
----------------------------------------------------------------------
// JS
var a = 1;
----------------------------------------------------------------------

[source,php]
----------------------------------------------------------------------
// php
$a = 1;
----------------------------------------------------------------------

Of course the [source] parts you add later, at editing time. While typing you just type the code.

Macros

Writing in your favorite code editor lets you come up with all kinds of macros and shortcuts.

Think about writing code MS Word. It's a pain. You write code and word mangles your "s and your 's. You undo. Copy the code, execute it somehow in a different program and/or terminal. See it has a syntax error. Fix it. Copy back to word. Then later decide to rename `foo` to something more informative. Repeat or risk publishing broken code.

In a code editor it's much easier, you write code in its natural environment. Then you can probably think of something to execute the code.

For me writing about JS and PHP it was two simple TextMate commands to run the code.

JavaScript:

#!/bin/bash
echo "$TM_SELECTED_TEXT" > ____.js
echo "<pre>"
echo `/usr/local/bin/node ____.js`

And PHP:

#!/bin/bash
php -r "{$TM_SELECTED_TEXT}"

I assigned shortcuts to these and then everytime I write some code in the book, I select it, press the shortcut and observe the result. Really quick feedback loop to fixing any errors.

In fact I have another JS TextMate command:

console.log('code: $TM_SELECTED_TEXT, result: ', $TM_SELECTED_TEXT);

Which makes it easier to spit out results.

Refactoring whole chapters and the whole book is also trivial when you deal with plain text (source code) in a source code editor.

Type all the things!

Removing friction out of typing is an enormous help. And writing a book in your favorite text editor and using something like AsciiDoc or markdown makes the process so much easier.

Another cool thing about O'Reilly specifically is that they give you an SVN repository where you check in your .asc files and images. Then they have a commit hook that generates a very production-like PDF (it's really asciidoc -> the weird book xml -> PDF) every time you commit changes, so you can see your creation formatted with all the O'Reilly styles, just like the real thing (barring some oddly positioned images, because of the autogeneration). The whole thing is not as immediate as edit-save-refresh web programming (it's edit-commit-wait-twitter-`svn up`-open PDF) but much better than the usual edit in Word -> send to Editor -> wait a month -> see the result

Writing vs. typing

Thursday, June 7th, 2012

Many people find the idea of writing a book or an article difficult. I think this is mainly due to a poor definition of what writing is.

In the movies, there is this romantic idea of the process. The author struggles, drama ensues. Then all of a sudden inspiration strikes. The author sits down all night just listening to what inspiration says and lo!, in the morning among a pile of cigarette butts and empty wine bottles, there is a brand new spanking chef-d'Å“uvre of a manuscript. Everyone who reads it says it's the best thing ever! Or, if the author is ahead of his time, as often happens in drama, at least those who know anything about anything and are not as dumb as the average Joe, love the thing. The author is done. Let's celebrate, while waiting for the next visit by her majesty, the Muse.

That's definitely not how it works with computer books. I don't have first-hand experience with fiction, but from what I've read from fiction writers, that's not how it works with fiction either.

When people buy into the romantic idea of the Muse and one-off writing sessions, and they try to write, no wonder they fail. Imagine out hero saying "heck! I'm going to write a book!". He creates a new folder, a new file called book.doc and proceeds typing the title: "Responsive Design with HTML5 and CSS3". He likes it. Next, a subtitle. "Unleash the power of mobile, social, local, yadda, yadda.". OK, so how big should the title be? What about the subtitle? 20 mins struggling with formatting options in Word. The future author goes: meh, I'll worry about formatting later. New page.

White page...

Big white page...

"History of HTML? Boring."

White page...

"Should I open with a joke? But what if it falls flat?".

White page.

Open the browser. Search "writer's block". Tweet about your writer's block... #fail

You see how the prospect of writing is scary for many people.

So what can you do about it?

Divide and conquer

You can split the process of writing in three phases.

  • Thinking: what am I going to say?
  • Typing
  • Editing: making what you typed readable

step #1: thinking

Most often people don't think about #1 as writing, But it is. It happens when you walk, bike, do the dishes, and most often in the shower. That's why the aspiring author should make time for those mindless activities.

There is a clear deliverable from this process: the TOC (table of contents). Bullet points of what you want to say. Probably split into chapters, although not until later in the process. The first part is just a list. A todo. You can use paper and pen. Or type in your phone if you don't have paper handy (you're on a walk). This is not as intimidating as the big bad Writing, because the outcome is 2-3 pages. Although the more, the better, because it means you have a detailed todo and don't leave much to think about in the next phase.

You can also take this TOC and do a slideshow. Give a presentation in a local meetup or your workplace. This is a nice checkpoint. If you're not confident people will be willing to listen to a talk, what makes you thing people will be willing to read a book about this topic. Each slide heading is a minor subtopic, a thought. Any words or code one the slides are the key points in the thought. When it comes to step #2, you can just copy-paste the slide and clarify the code or the key points.

step #2: typing

This is what people often refer to as writing and are scared of. But it's not writing. It's just typing. Mindless, easy typing. Anyone can do it.

You paste the TOC (or the slide content) and fill in the blanks. Add more explanation about what what you means with this item in your list.

It's very important that you don't read or edit at this stage. No formatting. No editing. No reading. Just typing away, filling the blanks. Just like filling our a form.

Like an email. Most people are OK with writing emails. They don't consider this writing. There's no writer's block. Someone asks you a question, you reply and type away. An email has a subject. What you're writing about has a subject (one of the TOC items). It's just like answering a question.

Next TOC item.

Next.

Before you know it, you've typed quite a bit. Resist the temptation to do editing. Keep typing.

I found it really helpful to set up time first thing in the morning and type for an hour or half an hour. It's awesome. It's the morning and you already have something done. Something is accomplished. Words are down on paper (of course you haven't read the words and you have no idea how bad the writing is, and this is a good thing). You feel good the rest of the day. Even if the rest of the day is just busywork and fixing urgent bugs or sitting in meetings or sitting in traffic, you have your morning, you have been productive already. In the night you may write more or you may not. You may enjoy going out or just being lazy.

So think of this stage as just typing which is easy and brainless.

step #3: editing

This is a read-write loop: you read what you wrote and you fix it. You move stuff around. You add, you remove, you refactor. Then you do it again.

You may be surprised initially that the stuff what you wrote in step #2 looks like, let me quote Frank Zappa here, some of the most terriblest shit you've ever known. But it's fixable. It's down on paper. Writing's done, you have pages and pages of text. You're an author! The rest is editing. And you can do it anywhere.

The typing is the only part that requires you to sit down in front of a screen. Thinking/TOC is done outside the four walls. I do most of my editing outside too. By the pool, the beach, even walking. I can do it in while in line at the store. You just print what you wrote and scribble on top of it.

I suggest the first edit is on the computer though because there will be too much scratching.

You can do the formatting in this stage. And print and edit. For some reason it's easier to spot mistakes in printed words. If you're into grammar checks you can also read backwards. For me, English is not my language, so I don't even try to fix grammar. That's you have an editor. If you don't have a publisher, I hear you can hire an editor.

Then there's the technical review, which is also critical. You try to find the best people on the topic to agree to read your stuff and point your mistakes. Because mistakes you will make. Fact of life, no matter how smart you are. So then another round of editing. Then the grammar Nazi kicks in and fixes your commas. And another round of editing.

All in all you'll spend more time editing than typing. Editing takes time. That's why you keep it off the typing phase. It takes time but it's not writing. Again, no writer's block here. You can do it outside in the Nature.

Misc

A few more random thoughts on the typing phase.

Douglas Crockford said in a talk that if you take all the code you've written in a year and just retype it, it will take only a day or two. Three. A week. Long, unpleasant days. But just days. So what are you doing the rest of the year. Definitely not typing.

The typing is to writing what a hackathon is to software engineering. The outcome is a hack. It's ugly but it works. It exists where it didn't exist yesterday. You've created something. It's relatively quick. Then you have to go back and make it right and solid and properly engineered.

Coding and writing technical books have similarities, but there's one difference: you can run the code and see if it does what it's supposed to do. With a book there are many right answers and outcomes that work. You just have to do enough of it to discover your opinion and feel for what works. The book is like source code that doesn't print anything out. So you're working to make the source code of the book readable and maintainable.

The blog hack

Forgot one more thing: blogging is a nice way to hack writing. You don't need a whole TOC, just one item. Then you type. Then you hit "publish". (ok, maybe read it once first, but then publish immediately). Then you edit if you want. No need to do much editing though. You have a feedback loop from the readers, if people point out mistakes in your logic, code, writing or whatever, it doesn't matter how polished and grammatically correct it is. You can edit the technical part first which is the most important. A technical book should first and foremost be technically correct.

Repeat the blog hack enough times on related subjects and voila, you have a book. You only need to tighten it up and do more editing.

Go!

Now go back to work! Stop writing and start typing already!

wordiness

Saturday, August 27th, 2011

Started (again, but this time immagonnafinish!) working on OOJS second edition. I'm finding some wordiness I'm gladly deleting.

"pretty" isn't

"Pretty" is just as bad as "very". And here's what Mark Twain has to say on "very":

Substitute damn every time you're inclined to write very; your editor will delete it and the writing will be just as it should be.

I had "pretty soon". That's just "soon".

I also had "pretty good". It can simply become "good", but I thought better yet why not try to find a more descriptive word. I had written that learning JavaScript is "a pretty good deal" because you learn one language and you can program for many different environments (shell scripting, mobile, etc). At the end I decided "smart investment" is much better than "pretty good deal".

more often than not

That's just plain "often".

-oriented

Thursday, March 25th, 2010

From The Elements of Style's chapter on Misused Words and Expressions:

-oriented. A clumsy, pretentious device, much in vogue. Find a better way of indicating orientation or alignment or direction.

They suggest instead of

It was a manufacturing-oriented company.
Many of the skits are situation-oriented.

it's better to say:

It was a company chiefly concerned with manufacturing.
Many of the skits rely on the situation.

So for the second edition of "Object-Oriented JavaScript" should I suggest to the publisher the title "JavaScript chiefly concerned with objects" or "JavaScript that mainly relies on objects" or maybe "Programming with the JavaScript Language while Mainly Concerned with the Use, Nurture and Care of Objects":)

Powered by WordPress, theme by ♣w3clubs.com, based on Kubrik and Sancta Simplicitas