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?

Chinese names and places always use pinyin romanization. See: Chinese, below.

Dates use ISO 8601 format: YYYY-MM-DD.

Dialogue is formatted using italics and double quotes for clarity, e.g. “Hello world,” she said. Also see: quotes and citations and chunkify.

Ellipses are used as a narrative device – not just to truncate quotes. Because this is not a newspaper…

Metric and imperial units are included in the e-book. Beijingers themselves will expect you not only to use the metric system but also local standards like jin and wan .

Numbers are never spelled out. Line length is short, and each character counts. (Names might be an exception, e.g. Three Shadows Gallery, and not 3 Shadows Gallery.) See: line length.

Styling content

Chinese

Include Chinese when it will help the reader, e.g.: names, landmarks. Imagine the reader pointing to this text when asking a passerby for directions, or when negotiating with a cabbie.

Pinyin romanization is always used. Do not include tone marks.

Chinese characters should follow the pinyin the first time a word or phrase is used. Chinese characters should be included in the location index, too. Use elsewhere as needed.

Chinese punctuation should be used for titles, dialogue and quotation. Again, this isn’t for the reader as much as it is for native speakers who the reader might consult, like a concierge or a fixer.

Also see: chunkify and lang, 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.

Small screens

Write for mobile. Keep paragraphs short, structure copy and visual queues to make reading in this environment easier.

Kindle and other reading apps do not give authors control over presentation width or line length. This can make reading feel breathless on narrower, mobile screens and exhausting on wider displays.

Thankfully, most apps give the reader some options within the settings to adjust margins, or switch to a 2-column layout. (How many readers know that option is there? How many toggle it on?)

Structure copy for quick answers

This is a reference book. The reader should be able to easily navigate info, and to hop back-and-forth without thinking about it.

(It’s like an offline internet. Perfect for travelers in China.)

Tone

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

  1. Don’t assume that the reader is from the US, or that her native language is English.
  2. TBH try to go easy on the abbreviations.
  3. For fuckssake, don’t say “fuck.” The e-book is meant for a wide-ish audience. Some people prefer plain prose without the pepper.

Quotes and citations

Quotes should be used sparingly because the reader is searching for quick answers. Paraphrase. Try to limit supporting info – e.g. links and quotations – to footnotes for any especially curious readers.

Citations in the e-book, like the rest of this website, use a bastardized variant of Chicago. (It’s a work in progress, I admit.)

Styling code

Chunkify

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

Use headers, short paragraphs, blockquote and bold text to help chunkify information. This is important for human readers, and also so that screen readers and reading apps can parse your text.

Be careful with <aside> because iBooks is idiosyncratic about displaying contents wrapped in this tag. For more, see Apple’s Apple Books asset guide.

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.

Be careful with <blockquote> because Kindle appears to overrides your CSS. See: Kindle CSS, below.

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:

Lang

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>

Line length

Line length can be a problem, watch out! Use CSS so that and printed URLs can break to a new line at the edge of the box.

Also see: small screens.

<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.