Author Archives: Sarah Maddox
When should we use one word, when should we use two, for terms like “log in”, “sign up”, “back up”, and the like? This is a hot topic among technical writers, UX writers, and any designers who use text in their products.
The question is particularly relevant in the software industry, but it affects other product areas too. For example, a gym may invite customers to an exercise class with wording like this:
We promise you a great workout
Work out with your friends and colleagues
How can we tell whether we should use one word or two?
Even if we ourselves already know the difference, how can we teach other people, like the engineers, designers, product managers, and other people who work on our product interfaces and documentation?
A presentation – a bit of fun with a serious goal
I’ve put together a presentation that explains a way to help ourselves and others decide when to use one word, when to use two. It’s a bit of fun, but with a serious goal.
You can find the presentation on SlideShare: One word or two? How to teach the difference between “login” and “log in”, and other mind-bogglingly important compound words.
This blog post contains some extracts from the presentation.
The presentation shows a couple of slides containing a few sentences. Embedded in the sentences are some strings of repeated letters, like lllll or bbbbb.
To play along, you’ll need to replace the string of letters with the terms “log in” or “back up”.
Try speaking the sentences in your head., or even saying them out loud. This is where the bit comes in about your partner needing to be in a good mood: you could even ask your partner to play along with you!
In the first slide, replace llllllll with “log in”
Here’s the first slide with letters for replacement – replace each series of lllll with “log in”. Don’t write anything down – just say the sentences in your head or out loud:
In the next slide – replace bbbbb with “back up”:
What’s the outcome?
Did you notice any pattern in the way you pronounced the words “login” and “log in”?
If you’re like me, your stress pattern in the middle sentence is different from the first and third sentences.
In the middle sentence, we give equal emphasis to both parts of the phrase: log in.
In the first and third sentences, we give greater emphasis to the first part of the phrase: login.
The stress patterns are the same for backup.
In the middle sentence, we give equal emphasis to both parts of the phrase: back up; log in.
In the first and third sentences, we give greater emphasis to the first part of the phrase: backup; login.
And it’s the middle sentence that uses two words, while the first and third use one word.
So, you can use stress patterns to decide whether to use one word or two.
That’s one way of doing things, but what’s the theory behind it?
The rules are something like this:
- If the phrase is acting as a noun, use one word. This includes cases when the phrase is used to qualify another noun.
- If it’s a verb, use two words.
The presentation goes into more detail and includes some sources and additional reading.
What about hyphens?
Yes, what about hyphens. I think this is my favourite slide, because it shows a pic of a Tawny Frogmouth. They’re the coolest birds ever.
I’ll leave you to read the rest in the presentation itself
The complete presentation is on SlideShare: One word or two? How to teach the difference between “login” and “log in”, and other mind-bogglingly important compound words.
(Note: This presentation is a prettified and updated version of my earlier blog post, published in April 2014. There’s a spider in that one.)
We’ve just announced the next Write the Docs meetup in Sydney:
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.
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!
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 (
My content is in Google Docs. This is the way I convert it to HTML:
- In Google Docs, make sure all chapter titles are at heading level 2.
- Convert the Google Docs content to HTML. I use the Chrome add-on GD2md-html, with its default settings for the HTML conversion.
- Save the result on your computer as an HTML file. Use any file name you like. For example,
- Open the HTML file in your favourite text editor.
- 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.)
- Optional, for better HTML semantics: Change all
- Remove the heading level 1 element that contains the title of the doc:
<h1>Remove this element containing your title</h1>
- Add an HTML
<title>element containing your title. Example:
<html> <head> <title>Put your title here</title> </head> <body> . . . </body> </html>
- Add an HTML
<body>tag directly after the
</head>tag, as shown in the example above.
- Scroll to the bottom of the doc, and add the closing
- Change all the
<h2>elements that contain your chapter titles, to include a page break element and an
idattribute, like this:
<mbp:pagebreak/> <h2 id="chapter-1">Chapter 1</h2>
<mbp:pagebreak/> <h2 id="chapter-2">Chapter 2</h2>
And so on.
- 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>
- Save the changes to
Here’s a minimalist sample for
<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 (
- Copy the example
toc.htmlcontent below, and save it with file name
toc.html, in the same directory as your HTML content file (
- Edit the file in your favourite text editor.
- In all the
your-book.htmlto the name of your HTML content file.
- In all the
hrefattributes, change the chapter IDs and chapter names if necessary, to reflect the ones you’ve used in your HTML content file.
- Add more list items to reflect all the chapters in your HTML content file.
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 (
The Open Packaging Format (OPF) file is an XML file that contains metadata describing your book.
- 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.htmlthen the OPF file must be
- Edit the file in your favourite editor.
- Change “Your Title” to the title of your book.
- Change “Your Name” to your name, such as “Sarah Maddox”.
- Change “Name, Your” to your name with your last name first, such as “Maddox, Sarah”.
- 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>
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 (
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
toc.html(use this file name)
your-book.opf(the file name is up to you, but the extension must be
toc.ncx(use this file name)
Step 6: Upload the zip file to Amazon
- Go to Kindle Direct Publishing. Sign in, or create an account if you don’t yet have one.
- Follow the prompts to create a new ebook and supply the requested information.
- When the Upload eBook manuscript option appears, click it.
- Follow instructions to upload your zip file.
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.
- Go to Kindle Direct Publishing (KDP). Sign in, or create an account if you don’t yet have one.
- Follow the prompts to create a new ebook and supply the requested information.
- When the Upload eBook manuscript option appears, click it.
- 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:
- 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.
- 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.)
- 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.
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.