/beijing  2022-09-18 📗 How and why I built this digital book the way I did.
Map and compass
Every project needs a map, a compass and a soundtrack.
All of my decisions are made using that map and compass. Reader feedback, and input from comrades who’ve generously helped me edit the copy and pictures in the book, have helped me refine those tools.
Soundtrack? I’m one of those people who puts a song on loop during a project, and I listened to Halsey’s cover of “The Sound” on BBC Radio1. While updating V2, I played Rosalia’s “Pienso en tu mira” like a ritual.


On the cover
Woo hoo, there’s a new cover for version 2! Type is Montserrat by Julieta Ulanovsky and Source Sans Pro by Paul D Hunt. I put the design together using Canva. It is quite a capable web app, I think. The Drum Tower in the picture is a historic landmark in the heart of the old city. That photo was processed using Nik Silver Effex. From there, I added a color gradient using Nik Color Effex to create the image used on the book cover.
Timeline
- V2.0.0: Jan 2020. Published via free EPUB, and on Kindle.
- V1.0.0: May 2017. Published on Kindle.
- V0.0.1: Oct 2016.
- Research begins in early 2015
The long way
From research, to draft and design, to marketing and shipping the final product, I wanted to be hands-on for the whole process. Trading efficiency for a fully DIY approach would give me important insight for the next book… Wouldn’t it?


Photos
Edit tight and compromise.
Each photo included in the Field Guide must:
- Tell a good story.
- Add context.
- Avoid redundancy with the usual stuff (Instagram, tourist guidebooks).
- Reinforce the tone and message of the Field Guide.
When I started the book, I asked myself a question: Does my reader even need to see the author’s photos? After all, she’s headed to Beijing to make her own.
Test it! In the beta that went out to a hardy group of testers (readers?), the only photo included in the Field Guide was on the cover. Reader response was unanimous: “Where the hell are the photos, man?”



Version 2
All photos are 1000px with a 1:1 ratio.
This update includes 3x more photos compared to the V1 field guide. The choice seemed straight forward: nearly everyone complained about the lack of pictures in the previous version.
While V1 only included monochrome images (which were chosen to reinforce the vibe of the book), I decided to ditch that approach this time because it wasn’t working for my readers.
Kindle V1 | Kindle V2 | EPUB V2 |
---|---|---|
11 photos | 37 photos | 37 photos |
7978 KB* | 13537 KB* | 9360 KB† |
*According to the Amazon product pages.
†According to my Github repo.
As you can see in the table above, the EPUB weighs less than the Amazon version, which is interesting because Amazon starts with that same EPUB file.
Amazon, iBooks and other platforms request authors upload “original, high resolution” files. (There are some good reasons to request this. There are also some sloppy reasons to request this.) Because I’m now distributing the field guide on Amazon and also directly as an EPUB, I optimized image files myself before before packing them. I need to keep my workflow streamlined:
- Keep photo dimensions “small,” at 1000px 1:1. Again, navigating with my map and compass.
- Compress image files using ImageOptim.
- Pack these files and build the EPUB file. (That EPUB is uploaded to my Github repo, and also converted to MOBI and uploaded to Amazon.)
Notes from V1: picture perfect?
According to the Amazon product page, the V1 field guide weighed 7978 KB. This is roughly the same file size as a hefty novel or nonfiction book – like Michael Meyer’s great book, “Last Days of Old Beijing.” (If you’re only going to read 1 book about Beijing, I suggest spending your time with Meyer’s book, and not mine.)
Book | Published file size |
---|---|
Photographers Field Guide V1 | 7978 KB |
Lonely Planet Beijing | 86787 KB |
Last Days of Old Beijing | 7559 KB |
Kindle is not a charitable platform for any kind of images – and delivering high-quality photography to readers is especially troublesome.1
Compare Kindle to Apple’s iBooks: Amazon charges authors by file size, for one thing. Meanwhile, the platform’s code limits the responsive options we all take for granted with modern web browsers. And readers’ devices run the gamut. (No more colorspace puns, I promise!)
Research told me many photographers are very choosy about their displays – my images would need to meet the demands of top-shelf phones and tablets.2
But device storage space is truly at a premium during international trips. An ebook like mine would be competing for space alongside movies for the flight, other ebooks and travel apps, and, most importantly for photographers, copies of their own images. It is easy to imagine a Reader backing up her photos to an iPad. She might also proof those images with an app like Lightroom, too.
So, I was much less concerned about showing off high-quality images in the book than I was with the risk of taking up space on Readers’ devices. Then there is that irritable warning from Kindle to customers: “Due to its large file size, this book may take longer to download.”
I assume I’m not the only one who tries to download just-one-more before it’s time to get on the plane?
I also assume that some of my Readers are in scenarios where network connectivity isn’t great.
Left to right: Schematic-like thumbnail map showing the city's 6 ring roads; Showing the 2nd Ring Road, the 6 lakes that make up Shichahai, and the Forbidden City; Detail of the red dot used on the thumbnail maps in the book. It shows the location of the Forbidden City.
Illustrations
To help orient the Reader, simplified, schematic-like thumbnail maps and a couple of visual symbols are used throughout the book.
If you can’t get there, you probably can’t photograph it.
The locations of places in the text are described in relation to landmarks like the city’s ring roads, the Drum Tower and the Forbidden City. The later 2 are treasured cultural sites, and the Forbidden City is on most visitor’s to-do list. In the context of wayfinding, you can’t miss it: it is at the very center of Beijing, covers over 70 hectares and is surrounded by vivid, red walls that are nearly 8 meters tall.
The Forbidden City goes by a few names, including 紫禁城. I have been told that the first character from that word, 紫, is a reference to Polaris, the North Star.

Red walls
A more common meaning of the character 紫 is purple 紫色. Maybe I am wrong but I think as a color term this word describes a warm-ish color with a little less blue, and more red. Something like: #400d2e
The red color of the walls surrounding Kong Miao and the Forbidden City is very distinctive, even if it’s not purple. I had initially wanted to use that red for the dot symbol in the book. Vermilion 朱色 comes closest to describing it, I think. It’s a bit earth-y and orange-y. In my mind’s eye it looks like: #b53d12
However, during beta testing on monochromatic e-ink screens, vermillion colors were not rendering with enough contrast against other visual elements. I needed something lighter. I consulted Ethan Schoonover’s Solarized color palate and opted to use his red: #ff5c5c
SVG GIF JPG wtf
All illustrations were created in SVG, which is a lossless, vector image format. Joni Trythall’s Pocket Guide to Writing SVG is brilliant, and I only wish I’d found it sooner.
Thumbnail maps were illustrated using Maperative on top of open-source OSM data. Some hand-polishing of the raw XML and the output SVG files was needed. Maperative is a brilliant tool although it takes some extra work to get it up and running on MacOS.
Originally, all the illustrations in the V1 field guide were to be published in SVG format, too. According to both the EPUB spec and Amazon’s spec for their own formats, SVG should’ve worked. Reality is not spec. Early tests (2016) revealed that, in fact, Kindle’s SVG support was too limited.
At that point I also learned that, apparently, some of Amazon’s e-ink hardware couldn’t render PNG. In the V1 field guide, it looked like my only options were JPG for photos, and GIF3 for everything else.
For the V2 field guide, it seemed that file format support had improved slighty for Kindle e-ink tablets. I used PNGs for the illustrations.
Copy
Version 2
Everything was written in Markdown, using TextEdit on MacOS. Then, using Pandoc, I built a rough EPUB. This was hand-polished with Calibre and BBEdit.
Calibre is very useful for editing and debugging EPUB files. Pandoc can be used for all sorts of things. Both have active communities. If you’re trying to build a book, try them out.
Gitbook changed their product offering, and wasn’t used in this version.
Version 1
My earliest drafts were puked out in MacOS’ TextEdit. Inevitably my best ideas were noted on-the-go with whatever was handy on my phone, including Evernote and video selfies. This mess was then assembled into a working draft.
As the project developed, I needed more structure. Gitbook allowed me to pull my disparate TXT files together. Writing in Markdown is great, so that’s what I did. Being able to easily add my visuals, and edit captions and other bits alongside the rest of the copy in Gitbook was very helpful.
From Gitbook, it was easy to export the whole thing as an EPUB. The output was chatty but good. Anyway, I still needed to get some things worked out in the XHTML files specifically for Kindle. For that, Paul Salvette’s books were an awesome resource for understanding what needed to be done. BBEdit and Calibre got me the rest of the way there.
Writing for mobile
Presentation width is important to the readability with any text.
- On narrow phone screens, short lines of text feel breathless.
- On wider screens, long lines of text are fatiguing.
Assuming that most Readers would be paging through the field guide on their phones and tablets, I wrote for that. And that took some practice. I reread the usual sources. I spent a lot of time working on the flow of information across sections, paragraphs and sentences. I refined my tone, syntax and word choice for the environment I assume my Reader will inhabit4 while reading the field guide.
The AP Stylebook might be Religion, but that good book provides no advice on typefaces, line length or other UI issues.
Butterick and the BBC did have some ideas. An English-language paragraph should be between 45 and 60 characters wide.
For the V2 field guide, I needed to step back and reorganize the book’s structure once again. Abby Covert’s book, “How to make sense of any mess” and Craig Mod’s essays were very helpful.

Lessons learned
The Photographers Field Guide to Beijing is the first book I’ve written. It’s not the first book I’ve helped produce, though. It’s also not my first big, hairy project.
There were a few false summits.
Again, I’d like to emphasize the importance of having a compass – you need to create a reader persona and learn to consult that document as part of your process. Mine is here.
- Find your beta testers (beta readers?) as soon as you can. Treat their time with respect. This feedback is invaluable.
- Find a good editor. If you’re including maps, illustrations and photos, pull in a photo editor or a designer, too. These eagle-eyed folks will catch mistakes and help you through the 11th-hour gales.
- I was told to divide my time equally between making and marketing. And I should’ve listened.
From the start I knew I wanted to do the whole thing myself. I wanted to understand how it works. It was worth the extra effort.
Notes
Note 1
There are several challenges with photos and visual content – and Amazon itself isn’t always the limiting factor:
-
File compression: Kindle automatically compresses images and the rest of the content you upload. This is probably in everyone’s best interest. The scant documentation on images doesn’t serve readers or authors well.
-
Resolution and colorspace: Mobile devices can be among the most demanding ways to view an image. That said, a 500 ppi mobile display and an e-ink reader with limited processing power want very different things from a photograph. Both Kindle gurus and the platform’s own documentation advise authors to consider their readers’ needs. Good advice!
-
Grayscale, btw: Kindle documention doesn’t mention which grayscale conversion standard they utilize (or if it’s proprietary, which some authors have asserted). I can only say that it’s worth testing your color illustrations on Amazon’s own e-ink hardware.
Note 2
DPI.lv helped me get a better idea of my reader’s resolution needs. Then it was time to experiment. Like the rest of the content, photos were tested on half a dozen different devices. Then I solicited feedback (and screenshots) from beta testers. Back ↩
Note 3
ImageMagick’s great convert
command let me quickly transform SVGs to GIFs. However, it did have some trouble with the bilingual copy on my maps.
I needed all the visuals to look consistent, and styled the text with a generic font-family="sans-serif"
. But ImageMagick stumbled with Chinese fonts. The program outputted Chinese text in serifed type, even though it outputted English text in the sans-serif I expected. As I couldn’t find a remedy, the SVG maps were converted to GIF using Inkscape instead. Back ↩
Note 4
With early drafts of the book, some Readers had trouble finding their way around.
I learned that information design, the flow and organization of ideas, is critical. Visual design is a distant second. Ebooks are far more austere than PDFs or webpages.
Internal, one-way links (e.g. A links to B but B does not link to A) were polarizing. One reader wanted more links, “make it like Wikipedia; link to everything”. However, most feedback on these links were complaints from Readers who were very frustrated, “I clicked the link and now I want to go back to what I was reading before – where is the back button?”
This surprised me because these Readers were used to hopping between Mac and Windows at work, used their phones constantly and, generally, spent lots of time living online. One of my blindspots was not recognizing just how clunky these older versions of the Kindle app could be. Readers to the rescue!
Ebooks are flexible like a webpage. You can stretch the page to fit a small screen or a one that is big. You can swap fonts. And like a webpage, an ebook must be interpreted by a browser.
Different apps make different choices about the app interface and how book content is displayed within the app.
A few Readers who were new to ebooks strongly preferred the iBooks app to the Kindle app. They found Kindle’s UI unintuitive and troublesome.
(To be fair, I think the Kindle app UI has improved a lot since we were testing early drafts.)
These Readers were frustrated because they couldn’t find the table of contents – much less the option to return to “last read”, or bookmarks, or formatting options that let them choose the font size, background color and the rest.
The experience of getting lost in the Kindle app was no different than getting lost in the book for these Readers.
Later on, I cut out all the one-way, internal links. Readers seemed happy to rely on the table of contents to navigate. Some apps present the table of contents at the beginning of the book, most apps display it as a dropdown menu.
And, with footnotes, I made sure to use 2-way links. Back ↩