Next Sydney Write the Docs meetup at Atlassian, July 3rd

We’ve just announced the next Write the Docs meetup in Sydney:

Sydney: Content strategy and more

Tuesday, Jul 3, 2018, 6:00 PM

Atlassian
341 George St, Sydney NSW 2000 Sydney, AU

3 Documentarians Attending

Join us to chat about docs – why they’re a Good Thing and how to make them even better. Tech writers, engineers, editors, product managers, more – if you’re interested in docs, you’re welcome. —————— Presenter 1: Michalina Ziemba Five steps to successful content strategy —————— More details and more presentations in the work…

Check out this Meetup →

What happens at the meetup

We currently have one speaker, Michalina, who will talk about five steps to successful content strategy.

There’ll be more speakers, and the opportunity to chat to old and new friends.

Who can attend?

If you’re interested in technical documentation, you’re welcome!

Date, time, and location

Tuesday 3 July 2018, at 6pm. We aim to finish around 7.30pm.

At the Atlassian offices, 341 George St, Sydney.

Want to air your ideas?

If you have an idea for a presentation or a lightning talk, let me know.

Thoughts on a remote Write the Docs meetup

On Wednesday this week, the Write the Docs (WtD) Australia group held a meetup entirely in cyberspace. Or, in the cloud, remote, virtual… whatever you’d like to call it. 🙂 Here are some thoughts on the experience.

Huge kudos to Swapnil Ogale for thinking up the idea of holding a remote meetup, organising it, and running it. It was a great idea and worked very well.

To attend the meetup, we all logged in to a GoToMeeting session. The meetup consisted of a few lightning talks and a couple of presentations. You can see the lineup in the meetup details.

The biggest takeaway for me is this:

People really do want to share their thoughts and experiences with others.

The lightning talks were a great way of doing that. Some presenters had slides, others just spoke from the heart. The variety of topics was intriguing, and listening to the talks was rewarding.

The chat screen was alive and humming throughout the meetup, with people commenting on the topic that the presenter was currently discussing, and on related topics, and on completely unrelated matters too. It was fun and enlightening to be able to watch the presentation and the chat at the same time. This is something that an in-person meetup doesn’t offer. During an in-person meetup, people sit quietly during the presentation, for the most part, and discussion happens afterwards.

It was good not to have to travel. I enjoyed the luxury of going straight home from work, powering up the computer, attending the meetup, then stepping out of the room to join my husband for dinner.

As with all meetups, whether virtual or in person, it was great to see everyone. Especially the speakers who enabled their video cameras so we could see their faces while they spoke.

The remote meetup was also a slightly scary experience, especially for me as a presenter.

I’ve jotted down some notes of what I found scary (I scare easily), primarily so people know they should persevere if they run into technical glitches when connecting to a remote meetup or presenting at one. Things usually work out!

We didn’t know which online platform we’d use until a until a few minutes before the meetup: candidates included Google Hangouts, YouTube streaming, or GoToMeeting. We eventually went with GoToMeeting, which worked well once it was working. I was on a Linux laptop, and the GoToMeeting compatibility checker told me I’d be unable to install the software (eek, but I’m presenting a talk!) but then it mentioned I could use the web interface. Why not just tell me all will be OK and leave it at that? Then GoToMeeting demanded a password, which I did not have. Swapnil was on that immediately, and sent a message to the group saying we should just enter a single space, which worked.

The next hiccup was audio. I couldn’t get mine working with the meetup platform on my laptop, so I dialled in on my mobile phone. All good, but five minutes later the meetup platform managed to find the audio on my laptop after all. Major audio feedback. So I had to decide whether to trust the software and kill the phone call, or mute the software and go ahead with the phone. I killed the phone call, which turned out OK, Luckily so, because by this time it was my turn to give my lightning talk.

When you’re presenting to a remote audience, it’s like talking into the void, You have no idea if people are still there. And I couldn’t get my speaker notes to play well with the meetup platform, so I had to speak without them. That went OK too!

Phew, presentation finished. It was very nice to hear people come back on the audio connection, and nice seeing the comments in the chat room about my talk.

My final thought is:

What a great community we have. Let’s do it again!

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.

 

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.

%d bloggers like this: