Style guide

Updated: • Like every project worth its salt, the field guide needed its own style guide. I took my sticky notes and organized them here. Maybe you’ll find this useful, too.

Mostly AP style?

Both the ebook and the mini site default to the AP Style Guide for spelling and punctuation. Yes, I do know that AP is obtuse at times. That’s why I break some rules:

Styling content

Chinese

When it might help the reader, include Chinese for locations, names, etc.

Chinese characters should follow the pinyin the first time a word or phrase is used. Chinese charaters should be included in the location index, too. Use elsewhere as needed. Imagine the reader pointing to this text when asking a passerby for directions, or when negotiating with a cabbie.

Chinese-language texts are styled with CSS so it’s easy for the reader. See: Chunkify and Multilingual, both below.

Photos

  1. Pictures should support the copy.
  2. Each additional picture adds weight to the ebook’s file size on the readers device.
  3. Most of all, each picture needs to tell a story.

Reference books, tho

Reference books are typically considered boring. Dirty little secret? This is a reference book. The reader should be able to easily navigate info and hop back-and-forth without thinking about it.

(Reference books are like an offline internet. Perfect for travelers in China!)

Small screens

Small screens are likely to be used by readers. It’s a travel book after all. Write for mobile: Keep paragraphs short, structure copy and visual queues to make reading in this environment easier.

Spelling

Spelling is American English or Pinyin Chinese. Readership includes English speakers from outside the US; it’s important to be cognizant of these things. For the same reason, it is important to use standards of measure that are international.

Both metric and imperial are used in the ebook. Meanwhile, Beijingers themselves will expect you not only to use the metric system but also local standards like jin and wan .

Tone

Tone should be personal and fun. Move it along because people need answers to their questions. The reader may already be on the ground.

TBH try to go easy on the abbreviations, and for fuckssake don’t say fuck. This book is meant for a wide-ish audience.

Quotes and citations

The AP stylebook is very clear: don’t use academic-style citations. That won’t work for my purposes. Otherwise, I do try to follow AP rules. E.g., “composition titles” and “quotations.”

Quotes should be used sparingly because this can disrupt reader’s search for quick answers. Ideally, paraphrase. Link/HT as needed. Otherwise, try and limit supporting info, e.g. quotations, to footnotes for the curious reader.

Citations in the ebook, like the rest of my website, use a bastardized variant of Chicago.

Styling code

Chunkify

Make the book easy to scan. See #2 and #3 under 10 Assumptions.

Kindle puts some limits on how this is implemented. Use headers, short paragraphs, blockquote and bold text to help chunkify information.

Blockquote

Don’t use blockquote for sidebars, info boxes or anything other than quotations. It’s semantically incorrect (even if markdown makes it easy). To visually separate info for the reader, use <span> or <div> and a bit of CSS.

For more, see: Apple Books asset guide

Icons

All the old, inline icons were removed for the v2 field guide.

Iconography within the v1 field guide was in GIF format because, after much testing, Kindle’s support for either PNG or SVG was a no go. Annoyingly there were still some issues with the GIF files that made them distracting enough to limit their usefulness.

Lesson learned? Keep it simple, folks.

Images

Within the ebook, images are 1:1 at 1000px. Photographs are JPG. Other visuals are PNG.

Kindle CSS

In my testing, it seems like Kindle overrides CSS styling for many html5 tags. I’ve had trouble with these:

Line length

Line length can be a problem, watch out! Unfortunately, Kindle gives authors no control over presentation width. This can make reading feel breathless on narrower, mobile screens and exhausting on wider displays.

At least the reader has the option to dig into the settings and switch to a 2-column layout. (How many readers know that option is there? How many toggle it on?)

Also see: small screens.

Be careful with links in the ebook. First, it annoyed beta readers to skip ahead and not be able to return to their previous location in the ebook. Second, external links to the web will likely be blocked by the GFW. This limitation is explained in the ebook.

<a href> is old-fashioned, underlined and #00f. Within the book, this is important for any users with monochromatic e-ink Kindle devices. The mini site uses #268bd2, inspired by the always-stylish Solarized.

Multilingual

Multilingual words and phrases are noted with <span> tags and CSS.

Chinese gets <span lang="zh"> tags.

The result looks like this: <span class="hilite">English <span lang="zh">汉字</span></span>.