Author Archives: Sarah Maddox

How to build an Amazon Kindle book via HTML and OPF

I’ve recently published a couple of books in Kindle format on Amazon. The latest is Words Words Words: A Trilby Trench adventure. It took me a while to get the publication process to work, so I’ve jotted down my notes in case they’re useful to others.

Please be aware that these are just my own notes, and are not intended as any sort of official or fail-safe way of moving content to Amazon.

Overview of my writing and publication process

I write my books online in Google Docs. That means I can access the content from any computer at any time, no matter where in the world I happen to be, provided I’m online. Google Docs also has an offline capability, but I haven’t used it extensively.

For the conversion to Amazon Kindle format, I use straight HTML rather than a Word doc or other format. I convert the content from my Google Docs file to HTML, using a Chrome add-on: GD2md-html. Why use the add-on instead of Google Docs’s own export to HTML functionality? Because I want a single, simple HTML file that contains just the content with minimal markup.

Then I hand-craft the files for the table of contents and other metadata.

Here are my step-by-step notes, in the hope they’re useful to other people.

Step 1: Create an HTML file containing the content of your book (your-book.html)

My content is in Google Docs. This is the way I convert it to HTML:

  1. In Google Docs, make sure all chapter titles are at heading level 2.
  2. Convert the Google Docs content to HTML. I use the Chrome add-on GD2md-html, with its default settings for the HTML conversion.
  3. Save the result on your computer as an HTML file. Use any file name you like. For example, your-book.html.
  4. Open the HTML file in your favourite text editor.
  5. Make sure the character encoding in your editor is set to something other than UTF-8. See Amazon’s documentation. (I ran into trouble when uploading my files to Amazon because the apostrophes, ellipses, etc, were using the default character encoding for my editor, which was UTF-8. On the Mac, Latin-1 (ISO-8859-1) worked for me.)
  6. Optional, for better HTML semantics: Change all em> to i>
  7. Remove the heading level 1 element that contains the title of the doc: <h1>Remove this element containing your title</h1>
  8. Add an HTML <head> and <title> element containing your title. Example:
    <html>
      <head>
        <title>Put your title here</title>
      </head>
      <body>
      .
      .
      .
      </body>
    </html>
    
  9. Add an HTML <body> tag directly after the </head> tag, as shown in the example above.
  10. Scroll to the bottom of the doc, and add the closing </body>and </html>tags:
    </body>
    </html>
  11. Change all the <h2> elements that contain your chapter titles, to include a page break element and an id attribute, like this:
    <mbp:pagebreak/>
    <h2 id="chapter-1">Chapter 1</h2>
    

    And:

    <mbp:pagebreak/>
    <h2 id="chapter-2">Chapter 2</h2>
    

    And so on.

  12. Optional: Add a welcome blurb at the top of the page, before your first chapter. Something like this:
            <h2 id="welcome">Welcome!</h2>
            <p>Welcome to <i>Your book title</i>, the crazy adventures
            of a possum in a puddle.</p>
    
  13. Save the changes to your-book.html.

Here’s a minimalist sample for your-book.html:

<html>
  <head>
    <title>Put your title here</title>
  </head>
  <body>
    
    <mbp:pagebreak/>
    <h2 id="welcome">Welcome!</h2>
    
    <p>Welcome to <i>Your book title</i>, the crazy adventures
    of a possum in a puddle.</p>
    
    <mbp:pagebreak/>
    <h2 id="chapter-1">Chapter 1</h2>
    
    <p>Your content, including simple HTML markup such as <i>italics</i>.</p>
    
    <mbp:pagebreak/>
    <h2 id="chapter-2">Chapter 2</h2>
    
    <p>More content.</p>
    
    <p>THE END</p>
  
  </body>
</html>

For more information, see Amazon’s guide to supported eBook formats.

Step 2: Create a table of contents file (toc.html)

  1. Copy the example toc.html content below, and save it with file name toc.html, in the same directory as your HTML content file (your-book.html).
  2. Edit the file in your favourite text editor.
  3. In all the href attributes, change your-book.html to the name of your HTML content file.
  4. In all the href attributes, change the chapter IDs and chapter names if necessary, to reflect the ones you’ve used in your HTML content file.
  5. Add more list items to reflect all the chapters in your HTML content file.

Example of toc.html – unfortunately, I had to paste this as an image, because WordPress won’t let me include the HTML for this file. (I tried all sorts of things, escaping characters, using HTML entities, etc, but nothing worked for this particular set of code.)

For information about the “landmarks” entry and other details, see Amazon’s guide to creating a table of contents.

Step 3: Create an OPF file (your-book.opf)

The Open Packaging Format (OPF) file is an XML file that contains metadata describing your book.

  1. Copy the example OPF content below, and save it in the same directory as your HTML content file. The part of the file name must be the same as your HTML content file. So, if your content file is your-book.html then the OPF file must be your-book.opf.
  2. Edit the file in your favourite editor.
  3. Change “Your Title” to the title of your book.
  4. Change “Your Name” to your name, such as “Sarah Maddox”.
  5. Change “Name, Your” to your name with your last name first, such as “Maddox, Sarah”.
  6. Change “your-book.html” to the file name of your HTML content file.

Example OPF file:

<?xml version="1.0" encoding="UTF-8"?>
<package unique-identifier="uid">
  <metadata>
    <dc-metadata xmlns:dc="http://purl.org/metadata/dublin_core" xmlns:oebpackage="http://openebook.org/namespaces/oeb-package/1.0/" xmlns:opf="http://www.idpf.org/2007/opf">
      <dc:Language>EN</dc:Language>
      <dc:Title>Your Title</dc:Title>
      <dc:Publisher>Your Name</dc:Publisher>
      <dc:creator opf:role="aut">Name, Your</dc:creator>
    </dc-metadata>
    <x-metadata>
      <output encoding="utf-8" output="text/html"/>
    </x-metadata>
  </metadata>
  <manifest>
    <item id="table-of-contents" properties="nav" href="toc.html" media-type="application/xhtml+xml"/>
    <item id="html" href="your-book.html" media-type="text/x-oeb1-document"/>
  </manifest>
  <spine>
    <itemref idref="table-of-contents"/>
    <itemref idref="html"/>
  </spine>
  <guide>
    <reference type="toc" title="Table of Contents" href="toc.html"/>
    <reference type="text" title="Beginning" href="toc.html"/>
  </guide>
</package>

For more information about OPF files, see the epub-boilerplate wiki on GitHub and the section titled “Finish your TOC” in the Amazon guide.

Step 4: Create a toc.ncx file – not sure this is needed

I’m not sure that you need a toc.ncx file for Amazon Kindle books. The Amazon docs seem to imply that you don’t need one. But I created one anyway, and included it in the upload of my book. I figure it may be useful for older types of devices that people may be using to read the book.

Below is an example of a toc.ncx file. Note the two attributes that increase incrementally: playOrder and the chapter number.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005-1//EN"
"http://www.daisy.org/z3986/2005/ncx-2005-1.dtd">
 
<ncx version="2005-1" xml:lang="en" xmlns="http://www.daisy.org/z3986/2005/ncx/">
 
  <head>
<!-- The following four metadata items are required for all NCX documents,
including those conforming to the relaxed constraints of OPS 2.0 -->
 
    <meta name="dtb:uid" content="uid"/> <!-- same as in .opf -->
    <meta name="dtb:depth" content="1"/> <!-- 1 or higher -->
    <meta name="dtb:totalPageCount" content="0"/> <!-- must be 0 -->
    <meta name="dtb:maxPageNumber" content="0"/> <!-- must be 0 -->
  </head>
 
  <docTitle>
    <text>Your Title</text>
  </docTitle>
 
  <docAuthor>
    <text>Name, Your</text>
  </docAuthor>

<navMap>
	<navPoint class="toc" id="table" playOrder="1">
		<navLabel><text>Table of Contents</text></navLabel>
		<content src="toc.html" /> 
	</navPoint>
	<navPoint class="titlepage" id="L1T" playOrder="2">
		<navLabel><text>Welcome</text></navLabel>
		<content src="your-book.html#welcome" /> 
	</navPoint>
	<navPoint class="titlepage" id="L1T" playOrder="3">
		<navLabel><text>Chapter 1</text></navLabel>
		<content src="your-book.html#chapter-1" /> 
	</navPoint>
	<navPoint class="titlepage" id="L1T" playOrder="4">
		<navLabel><text>Chapter 2</text></navLabel>
		<content src="your-book.html#chapter-2" /> 
	</navPoint>

</navMap>

</ncx>

Step 5: Zip all the files (your-book.zip)

Zip the following files into a zip file named something like your-book.zip (the name of the zip file is up to you):

  • your-book.html (the file name is up to you, but the extension must be .html)
  • toc.html (use this file name)
  • your-book.opf (the file name is up to you, but the extension must be .opf)
  • toc.ncx (use this file name)

Step 6: Upload the zip file to Amazon

  1. Go to Kindle Direct Publishing. Sign in, or create an account if you don’t yet have one.
  2. Follow the prompts to create a new ebook and supply the requested information.
  3. When the Upload eBook manuscript option appears, click it.
  4. Follow instructions to upload your zip file.

Troubleshooting

When things go wrong, the error message you get from KDP isn’t very helpful. It basically tells you that there was an error processing your file, and you should check your files.

A couple of issues I had, which may help you diagnose any problems you come across:

  • Check the little things, like syntax bugs a copy/paste errors. In the book’s content file, one of the id attributes for my chapter headings was wrong. In effect, I had two headings with id="chapter-2", and none with id="chapter-2". KDP was happy when processing the content file alone, but gave an error as soon as I tried to hook it up to the toc.
  • Character encoding is a hassle. I ran into trouble with apostrophes, ellipses, etc, because the default character encoding for my editor was UTF-8. It’s safest to set your editor to use ANSI. See Amazon’s documentation.

Hint: If things go wrong, try uploading just your HTML content file

If you can’t get your toc and OPF files to work, one trick is to first upload just your HTML content file to Amazon KDP, then download the resulting Kindle file from Amazon and adapt it.

  1. Go to Kindle Direct Publishing (KDP). Sign in, or create an account if you don’t yet have one.
  2. Follow the prompts to create a new ebook and supply the requested information.
  3. When the Upload eBook manuscript option appears, click it.
  4. Follow instructrions to upload your HTML file.

Amazon KDP takes your HTML and creates the basic set of files that it needs to make a Kindle book. You can now make use of those files. So, when the upload is finished, follow these steps to download the results as a zip file:

  1. Still in KDP, scroll down to the Kinde eBook Preview section and click Preview on your Kindle device. A small section open on the page.
  2. In the section that opens on the page, click the HTML link in the first bullet point. (The text is “Step 1: Download your converted book file: HTML or MOBI.)
  3. Wait for the zip file to download, then unzip it on your computer.

Now you can continue working on the files as described earlier in this post, and upload them again as a zip file. You can download and upload as often as you need.

Other useful resources

Perry Garvin has written a useful article on making a Kindle book with HTML and CSS. I follow a different procedure from the one mentioned in that post, but the description of the files, and the sample doc set are very useful.

Amazon’s KDP Jumpstart is a good entry point into the world of Kindle Direct Publishing.

 

Advertisements

New Trilby Trench action novel – Words Words Words

I’m thrilled to announce the publication of the latest Trilby Trench action book, Words Words Words!

Trilby Trench’s worst nightmare comes true. Her friend Bonnie goes missing. The last message from Bonnie came from a remote location in Australia’s Top End. Since then, nothing. Has Bonnie simply gone walkabout, or has some mishap befallen her? It’s up to Trilby to find out.

There are times when words are evil. Times when words cause nothing but trouble and strife. That’s when you need someone who knows their way around a sentence and around a fight. Someone like Trilby Trench.

The complete book, Words Words Words, is available on Amazon as a Kindle ebook (USD $3.99) and as a paperback (USD $8.99).

Looking for a quick taste of the story? I’ll publish a few chapters on the Trilby Trench site. Chapter 1 is available now.

The Trilby Trench action adventures so far:

  • The first book in the Trilby Trench action series is A Word If You Please. It’s quite short – the length of a novella. It’s a great introduction to Trilby and friends. You can read the entire book here on the Trilby Trench site, as well as getting it in Kindle or paperback from Amazon.
  • The latest book, Words Words Words, is a full-length novel. The book contains around 67,000 words, and the paperback version is 361 pages.

If you’ve read either of the books and would like to add a book review on Amazon, that’d be awesome! Here’s my author’s page.

The art, and the power, of saying no

Recently, I needed to let a product team know that our tech writing team couldn’t take on the task of creating a particular doc. The doc was outside our normal area of responsibility, but one where we could certainly have added value. The problem was, we just didn’t have bandwidth. My manager showed me a published procedure which outlines our priorities. It was very useful to be able to refer the product team to the procedure, and to have at my disposal those words in the procedure which had been so carefully written for just this sort of situation. I was also able to offer the product manager our help in reviewing the doc once the engineering and product teams had created it.

This experience led me to think about the art, and the power, of saying no.

Saying no feels bad. You’re letting the side down. You and your team are underachieving.

Not so. I’ve come to the realisation that saying no is a good thing, provided it’s done under the right circumstances and in the right way. It’s good not only for you, but also for the people you say no to, for your manager, and for your team members. Even more, it’s good for the organisation as a whole.

How so?

When an organisation has had the luxury of a tech writer or two for a while, people start appreciating the skills we offer. They start asking us to create documents that are urgent, high profile, sales critical, and more, but that are sometimes outside our scope.

It’s fine to help out if the tech writing team has time. But often the team is fully taken up in other work that’s of equally high priority, and which is part of our primary responsibility. In such cases, it does the team and the organisation a disservice to say yes. Writers will end up working overtime, or the  docs under our primary care will suffer.

If we say no, people in the organisation may realise they need to hire more tech writers. In many cases they already know they need more writers, and our saying no can give them the data they need for their hiring requests.

Tips

If time allows, it’s good to be able to offer a little more than just a “no”. Here are a few ideas. Some of them involve preparation ahead of time, under the assumption that you’ll have to say no at some time:

  • Write up your team’s policy and responsibilities clearly, so you have somewhere to direct people to when they ask the impossible. Don’t be afraid to adjust the policy doc as time goes on, and as your team changes or you discover more situations which you can or cannot support. The team’s policy is not set in stone. It changes with your team, your stakeholders’ teams, and the organisation as a whole.
  • If you have a helpful suggestion or recommendation, include it when you say no. For example, point people to templates and style guides that will help them write the doc themselves. Look for existing documentation that may be similar to what they want.
  • If you have the bandwidth, offer to review the final draft after another team has created it and pushed it through initial review.
  • Encourage the product and engineering teams to contribute to the docs on an ongoing basis, so that they’ll feel able to write their own doc in this sort of situation. Create a quick-start guide to your doc tools and review procedures, and point them to that guide. On the topic of writing such a guide, you may find this post useful: the importance of audience.

Have you found yourself in a position where you’ve had to say no, even though you know that you and your team would add value to a task if you had bandwidth? I’d love to hear any tips you have on how to handle this sort of situation, and what you’ve learned from saying no.

The importance of audience, or, how to scale a tech writing team

A recent experience brought home to me how important it is to take account of the audience of a document. It also showed me how a well-tailored doc can help people perform tasks that they may need to do only rarely, but that are highly important when they do need doing.

Here’s the story, which you could entitle, The importance of audience, or, how to scale a tech writing team, or, how to encourage engineers to write documentation.

Over the last few weeks I’ve worked with a small tech writing team to create a documentation set for a product launch. It was a highly technical product where, by necessity, engineers wrote much of the material. In particular, we provided a number of tutorials that show customers how to run specific, optimised machine learning models, and we published best practices for people who want to customise the models.

In the leadup to the launch, new tutorials and updates were coming in thick and fast. Too many for a small tech writing team to handle. We needed the engineers to write the initial versions of the docs, and to send them to us for review and publication.

So, we needed a guide that would help the engineers write docs for our documentation site.

Now, of course, we already have plenty of guides for tech writers, telling new team members how to use the various editing and review tools. You’d be tempted to point the engineers at those guides and say,

“Go, do the same.”

That doesn’t work too well. The engineers tend to get lost in a sea of documentation that doesn’t answer their questions.

TL;DR: The audience is different.

  • New tech writers need to know how to use all the editing and review tools, as well as the tools for publishing a doc on the test site, and the processes for reviewing and publishing changes.
  • The engineers know most of the tools and processes already, since the docs are in the same repository as the code that the engineers work with every day. The editing tools and review tools are the same too. Even the source format (Markdown / HTML) is familiar. All the engineers need to know is:
    • Where to find the doc source, which is in the same repo as the rest of the code that they work with every day.
    • That the editing and review tools and processes are those they use every day too.
    • How to stage a doc on the testing site.
    • Who will do the doc review and publication.

To help the engineers get started quickly with writing docs, I patched together a very short guide containing the information outlined in the above four points.

The short guide also focused on command-line tools rather than GUI, whenever there was a choice. Most engineers prefer the command line, as it’s where they spend most of their time. Learning the peculiarities of a GUI for a task they’re not going to do every day is a waste of time.

The short guide worked a treat. We had plenty of high-quality material coming through the pipeline. The engineers and the tech writers worked together efficiently, fast, and happily. A very small team of tech writers was able to produce high-quality docs on time, and stakeholders were pleased with the result. I think the engineers had fun too.

Giving a specific doc to a specific audience works!

Of course, the trick is to find out who your audiences are, what they need, and which of them are worth the extra work of receiving a doc tailored specifically for them. Another post, anyone? 🙂

 

How to moderate data input into a spreadsheet

A smart engineer suggested a lightweight way of moderating data coming into a Google Sheets spreadsheet. I’m sharing it here in case you find it useful. Note that this is not an official Google solution, and anything on my blog is my own opinion or idea, not Google’s.

This idea came from François Wouts, as a lightweight way of moderating anonymous data coming into Tech Comm on a Map. The data source for Tech Comm on a Map is a Google Sheets spreadsheet. People contribute data entries anonymously from all over the world: conferences, meetups, educational courses, businesses. They enter the data via a web form or via an option in the Android app for Tech Comm on a Map.

It’d be a pity if something weird ended up on the map. I needed some way of moderating the incoming data before it ended up on the map.

The solution comprises two spreadsheets and a formula:

  • The first sheet accepts the data entered via the form. Anonymous data comes into this sheet via the web form and the Android app.
  • Also on sheet 1 is an extra column containing a value that indicates whether each entry is accepted or not. When entries come into the sheet, the column is empty. When moderating the data, I can mark each entry as accepted or not accepted by entering a value in that column
  • The second sheet contains a formula that copies the data from sheet 1. It copies each row where the “accepted” column is set to yes, and ignores the other rows.
  • Sheet 2 is protected from public editing. The app draws its data from this sheet.

Here’s the formula that copies the data from one sheet to the other:

=QUERY(ImportRange( "MY-SPREADSHEET-ID" ,
"MY-DATA-ENTRY-SHEET-NAME!B2:K2000" ) ,
"Select * Where Col20 = 'Y' " , 0)

If you’d like to use this technique, create a Google Sheets spreadsheet doc containing 2 sheets:

  • Sheet 1 will contain the unmoderated data items. Any web form or app should write to this sheet.
  • Sheet 2 is your protected data sheet. This is the sheet from which your app should draw its data. See the Google documentation for help on protecting a sheet.

Then apply the formula to your sheets as follows:

  • Copy the above formula.
  • Replace MY-SPREADSHEET-ID your own spreadsheet ID. This is the ID of the Google Sheets doc. The ID is a long string of numbers and letters.
  • Replace MY-DATA-ENTRY-SHEET-NAME with the name of your sheet 1. This is the sheet that accepts data entry via a form.
  • Replace the cell range B2:K2000 with the location of the columns and rows in sheet 1 containing your data.
  • Adjust the column number in Col20 to reflect the number of the column containing your “accepted yes/no” indicator.
  • Paste the adjusted formula into the top left cell of sheet 2 in your spreadsheet. This is the protected sheet from which your app should draw its data.

I hope this is useful. I was delighted when François suggested it, because it’s lightweight and simple to implement.

%d bloggers like this: