mike's web log

Twenty years ago today, I posted the first entry on this blog. As I’ve recounted, I wrote some blog software as an outgrowth of a book project I’d been working on. The book purported to teach people how to program websites, and a blog seemed like a good exercise to test that.

It’s hard today to remember how exciting the idea of blogs was 20 years ago. Before then I’d contributed some articles to a couple of specialized publications, and I was proud to see those in print. But dang, with blogging, you could sit at your desk and draft something, press a button, and presto, anyone in the (connected) world could read it instantly.

In the early days, there was handwringing and skepticism about blogs. “The blogosphere is the friend of information but the enemy of thought,” according to Alan Jacobs.[1] And in an editorial in the Wall Street Journal, Joseph Rago dismissed blogs as “written by fools to be read by imbeciles.”

Despite these Insightful Thoughts from pundits, somehow blogging survived. (haha) In my world—software documentation—blogs turned out to be perfect for a niche that otherwise could be filled only by conference presentations, or occasional articles, or books. Blogs became a way to get news and information out fast. They were also unfiltered, as compared with company-created documentation: authors could provide personal and opinionated information. And in blogs like The Old New Thing (about Windows) and Fabulous Adventures in Coding (about programming languages), to name only two, readers got all sorts of insights into how and why software was developed as it was.

And it was all free!

Once blogging overcame the initial doubts, people and companies were keen to learn how to do it. In the mid-oughts, I was teaching classes in Microsoft Word and in editing at the local college. The woman who ran the department called me up one day and said “I think we need a class about blogging.” So I put together a curriculum and taught that class for a couple of years. Which naturally I blogged about.

A bit ironically, in my own blog I didn’t follow some of the advice I was dispensing. My subject matter was (is) all over the place, as the Categories list on the main page suggests. I also was not very disciplined about adhering to a strict schedule, about planning my posts around specific dates or events, or about optimizing for SEO. (In my defense, I’ve never thought of my blog as a commercial project, so I wasn’t very concerned about maximizing traffic, building a corporate or personal brand, etc.)

And here it is, 20 years on. Counting this entry, I’ve made 2,648 posts. A rough count tells me that I’ve written almost 900,000 words. The pace on this blog has slowed considerably, but the process has been valuable to me in many ways:

• Blogging is writing. Putting together all those blog posts has given me lots of practice and I’m sure it’s improved my writing skills.
• It’s a resource. Countless times I’ve reached back into the blog to look something up that I wrote long ago.[2]
• It’s helped people. Perhaps the high point was when some Microsoft documentation pointed to one of my blog entries as the quasi-official story on something. Per my reckoning, the blog has gotten about 2.5 million hits, so hopefully some folks have gotten some value there.
• I "met" many people via blogging, and some of those in real life, even.
• It’s helped me in my career. I’ve used the blog to (in effect) draft things that were later turned into “real” documentation. I’ve used blog entries as writing samples when applying for jobs.

But over time, a couple of things changed. One was that Google killed Google Reader, a tool for tracking blogs, citing declining usage. This seemed to indicate that the popularity of blogs had crested, but I think that that change itself also contributed to making it harder to keep up with blogs.

The real change, of course, was social media. In particular, Twitter, which sometimes has been referred to as a “micro-blogging platform”, really took the air out of blogging. (For example, you're probably reading this because of a link on a social media site, not because you saw the post in your aggregator app.)

Although Twitter isn’t a good way to capture long-form posts, its immediacy became the default first-reaction medium for breaking news. And it was a perfect way to post from a smartphone; Twitter’s original 140-character limit was dictated by the constraints of the SMS protocol that was used with phones. Some will remember that as with blogging, early Twitter faced skepticism—“Why would I want to know what someone had for lunch?” for example—but it, too, found its footing.

But, gee, what goes around. In 2012, right about the time that Google Reader went away, the Medium website was launched. “Williams, previously co-founder of Blogger and Twitter, initially developed Medium as a means to publish writings and documents longer than Twitter's 140-character (now 280-character) maximum.” (Wikipedia) And there’s also Substack at al., platforms that let authors publish newsletters, as they call them, and push them to your email. Maybe I’m a bit cynical, but the difference between a blog entry that appears in your aggregator and a newsletter that appears in your inbox seems pretty small to me.

Although the software that originally inspired this blog (Web Matrix) is long gone, the blog persists. For about 19 years, I’ve been telling myself that I’ll rewrite the code to modernize it. We’ll see.

It’s had a good run, this blog, and I think it still has value to me and who knows, maybe to others. I’ll check in again in five years. :)

[1] He updated that thought a few years later.

[2] The funniest example of this was just recently. I was having an issue with the blog, so I did a search on the error message I was getting. Google pointed me to an entry on my own blog that outlined the fix.

Part 4 of a series about what I did to self-publish an ebook and then a paperback version of it.

• Part 1: The original manuscript
• Part 2: Formatting the Kindle ebook
• Part 3: Publishing the ebook
• Part 4: Formatting and publishing the paperback (this entry)

This is the final part, which is about creating a manuscript for print and then publishing the book on the Amazon site as a (print-on-demand) paperback. This entry covers a lot:

• About formatting for print
• The Kindle paperback template
• Paragraph formatting
• Body text
• Widow and orphan control
• Body text after headings
• Headings
• Page headers
• Page footers
• Related terms
• Footnotes
• Rethinking footnotes
• Links
• External links
• Internal links
• Hyphenation
• What about indexing?
• Checking the layout
• Configuring KDP for publishing the paperback
• Cover art
• Upload and preview text
• Ready? Not quite yet
• Ok, now for real
• Linking book formats
• Lessons and what's next

About formatting for print

When you format for print, what you see is what you get. Unlike an ebook, your choices about typeface, font size, paragraph spacing, etc. are reflected directly in the final product. And you need to worry about page layout: page breaks, page numbers, headers and footers, etc.

When I was formatting the paperback version of the book, I pulled books off my shelf and studied their formatting and layout. There's a whole art and science to book layout, of which I know some rudiments. I reckoned I could do worse than try to copy how they did things in professionally formatted books.

Because someone asked me about this, I'll note that the book uses only two fonts. Body text is Times New Roman. I used a sans serif font (Calibri Light) for headings, headers/footers, and a few other purposes, as I'll explain. My choices here were all conservative and possibly even boring. I don't know enough to try to be creative in this sphere.

The Kindle paperback template

One of the formatting decisions for the paperback edition is to choose the book size ("trim size"). Amazon has Word templates that you can download for different trim sizes. The templates include sections that have predefined margin sizes and that are set up to have right/odd pages (recto), left/even pages (verso), and gutters. When they say "template," however, they don't mean a Word template—a .dotm file—just a .docx file with predefined settings and some sample content.

I made a copy of Amazon's 6 x 9in.docx template, which is a standard size for trade paperbacks (in the US, anyway). Their template has different sections (in the Microsoft Word sense of "section")—a section for the title page, another section for the copyright page, and sections for the table of contents, the acknowledgements, and of course a section for the main text. The point is to allow you to control pagination and headers/footers separately for each of these sections.

Once I had the template, I copied the contents of my original manuscript (not the ebook manuscript) into the section of the 6 x 9 doc that was for the body of the book. Then I did the title page in the title-page section, and so on. Then I got to work at formatting this manuscript for a print book.

If you've been following along, this means I now have three versions of the manuscript (original, ebook, print). As I was fooling around with book formatting, I found more content issues, so I had to make changes in all three versions of the document.

Paragraph formatting

It's common in books for text to be justified. In running text, there aren't blank lines between paragraphs. The first line of a paragraph is indented unless it follows a heading or other break in the text. Books also have page headers and footers.

To implement all this, I tweaked and amended the formatting of the Word styles I was using. Here's a diagram that captures a lot of this, with descriptions afterward.

(Click to embiggen)

A. Body text

I adjusted the settings for the Normal style for book layout: I set alignment to justified and I indented the first line. I also set line spacing to 1.12 to give the text a little breathing room but not too much.

For the typeface, I chose Times New Roman 11 pt, and I used the font-formatting option to set kerning for 11 points and larger. My thinking here is that the tool probably has more smarts built into it than I do about text layout, so I should take advantage.

B. Widow and orphan control

You don't want page breaks to leave individual lines dangling at the end or beginning of a page, aka widows and orphans. As with book design generally, there's a craft to this. I enabled the Widow/Orphan control setting for the Normal style. (Probably not what a professional book designer would do? I don't know.)

C. Body text after headings

I had to create a new style (Body after heading) that was the same as Normal except that the first line wasn't indented. I then had to go through and manually apply that style to any paragraph that followed a heading, a diagram, a blockquote, an example, or a list.

D. Headings

For headings, I used the contrasting, sans serif typeface (Calibri Light), bold. I ended with Heading 1 at 18 points and Heading 2 at 13 points.

For the heading paragraphs, I enabled Keep with next and Keep lines together, but I disabled widow/orphan control. I also set some space before and after the heading-style paragraphs.

E. Page headers

For print, you also need page headers. The Kindle template is set up to allow different headers on odd (recto) and even (verso) pages. As noted, it also lets you set different headers and footers for different sections.

In the body part of the book, for the headers on even (left) pages, I used the name of the book. For the headers on odd pages, I used the STYLEREF field set to Heading 1; this shows the text of the current Heading 1 paragraph. (See Rhonda's explanation.) As you can see from the diagram, the result was that when the book was open, the title was on the top left and the current entry was on the top right.

There are no headers or footers for the introductory sections of the book (title page, copyright page, TOC).

For the page headers I used the contrasting font (Calibri Light) and set it to 10 pt instead of the 11-pt size that's in the body text.

F. Page footers

I used the page footers for page numbers. I set up page numbering to start at 1 in the main section of the document. You can't see it in the diagram, but for the preliminary pages in the book (table of contents, intro), I set up page numbering to use small roman numerals (i through iv). The section for the title page and copyright page has no page numbering.

G. Related terms

In the original manuscript, the "Related terms" list at the end of each entry was a Heading 2 paragraph followed by a paragraph styled Related terms list. (Earlier explanation) I'd created this style to be able to control its formatting separately from the spacing (etc.) of the Normal style. For the print book, I thought having an H2 + a separate paragraph took up too much space in the book. I ended up removing the text "Related terms" as a separate heading and I just added it to the beginning of the list. This was a manual process, with an assist from find-and-replace.

This is what it looks like in the ebook manuscript:

And this is what it looks like in the print manuscript:

H. Footnotes

I changed the settings for the Footnote style to use be 9.5 points. However, I didn't use footnotes in the print book the same way I had in the original manuscript, as I explain next.

Rethinking footnotes

As noted before, I had a lot of notes/footnotes in my original manuscript. For the ebook, I'd done work to make these into links to end notes at the end of each entry.

For the print book, given especially the small format (6x9), the footnotes took up a lot of space at the bottom of the page. (IOW, they didn't look as clever in the print book as I'd thought when I wrote them.) Also, I needed footnotes for a different purpose.

So I removed almost all of the informational footnotes. Instead, I integrated the footnote text into the body text, sometimes parenthetically.

Links

A big dilemma was what to do about links. The ebook had links to outside sources, and it had many, many cross-links within the book to related terms. I ended up doing several things. This included adding a paragraph in the introduction that spelled out my conventions, which I'd also had to do in the ebook.

External links

For external links, I went through one by one, copied the URL of the target, and put that target URL into a footnote. In a few instances, the URL was so long that I used a URL shortener. After I'd added a footnote for an external link, I removed the Hyperlink style of the original link. This was a manual process.

In case you're wondering, I experimented with putting the URLs directly into the body text. Not only did this look awful, but it messed up the formatting (justification) in the paragraph.

The original looks like this in the ebook manuscript:

And it looks like this in the paperback manuscript:

I also removed some of the external links altogether. Some number of the links felt like they weren't all that necessary—more CYA than FYI. The rough rubric I used was whether I thought that the intended reader for the book would find the external source interesting enough. I did this pretty quick, so I probably made a few bad calls, dunno. This means that there are some small content differences, citation-wise, between the ebook and the paperback.

Internal links

For internal links—cross-references to other entries in the book—I created a new style called Cross-reference. This new style uses the contrasting font (Calibri Light) and has no color or underlining. Since I'd already removed all the external links, I changed the remaining instances of Hyperlink style to use the Cross-reference style. (You can do this in the Styles pane, as Rhonda Bracey explains.)

The result was that something that originally looked like this in the ebook:

… looks like this in the print book:

I'm reasonably happy with this solution.

Hyphenation

When text is justified, you can get some weird spacing in a paragraph unless you enable hyphenation. So in Word, I enabled automatic hyphenation. Word did a pretty decent job of hyphenating words.

What about indexing?

An ebook can get by without an index if you accept that searching the ebook is a workable substitute. Print books ... well, they should have an index, right? I did not create one/have one created. My very weak justification is that my book is in some ways an alphabetical reference, so if I want to look up, say, "biscuit conditional," why, it's right there in the table of contents. But I do recognize that there are many terms in the book that don't have headwords and that the book definitely would benefit from a real index. Perhaps for the next edition?

Checking the layout

Ok, whew! After I'd made these adjustments to the formatting for the print book, it was time to check everything. I saved the document as a PDF file (the format that Amazon wants) and then paged through it. I did all of these checks:

• Make sure new each new section starts on an odd (recto) page. Not each entry, but each section (TOC, Introduction, etc.)
• Check for bad page breaks e.g. leaving a heading by itself, or awkward gaps between entries. I fixed some of these with small adjustments, such as slightly resizing images, or adding or removing small amounts of space around images, block quotes, or cites. This is part of the craft of book design, and there's much here for me to learn.
• Check for widows and orphans.
• Check for bad hyphenation. I attempted to review every instance of auto-hyphenation in the book. In the end I found only, like, 4 words that were awkwardly split. Interestingly, while checking, I discovered that Merriam-Webster and American Heritage sometimes have different ideas about how to hyphenate.
• Check that the TOC page numbers were correct. I had to remember to refresh the TOC every time I did anything that affected page flow.

This was an iterative process—if a change affected page flow, I had to recheck everything that followed the change. I don't know how many times I went through the book, but it was a lot. And naturally I still missed stuff, because self-editing is hard.

Configuring KDP for publishing the paperback

After all this reformatting, I was ready to set up the print book on Kindle Direct Publishing (KDP). I created a new project and chose the option to create a paperback. Some of this process is similar to how you set up a Kindle ebook—do you have your own ISBN? What price do you want?

But the print version has a couple of additional options and steps. What color paper do you want? Should the cover be matte or shiny? These choices seemed straightforward to me.

They also ask about Territories, which has something to do with distribution rights. I went with the default ("All territories"). They also ask about Primary marketplace, which is basically which national flavor of Amazon you want to use for your book—for example, Amazon.com versus Amazon.co.uk. This is interesting for international sales and for calculating prices and royalties. I have no advice for you, though.

A few print options required some work.

Cover art

For the ebook, you have to provide just a cover image. But for a printed book, you have to provide the entire cover: front, spine, back. Ideally, they want a PDF or TIFF file that has text and art for this three-sided cover. They have a template for this.

Fortunately, they also provide the Cover Creator tool. The tools let you enter text for the summary (back cover), author bio (also back cover), and for the spine (title and author). You also upload the cover image. The tool has a certain number of knobs and levers, like font choices and a few layout options. It's okay; I wasn't super pleased with the resulting cover. If you have the skillz, you can probably create a much better cover with e.g. Photoshop. This is what the cover looked like in Cover Creator when I was done:

Upload and preview text

For the text, you upload a PDF file that you create from your Word document. They then really want you to preview the book layout. You might think that you'd already done that in Word and then perhaps after you created the PDF file. But the KDP preview is definitive—it shows you exactly what your printed book is going to look like. I'd encourage you to flip through your entire book yet again, again looking for weird page breaks, odd formatting, or whatever.

If you spot something (I did, multiple times), you can fix it in the Word file, re-save as a PDF, re-upload the PDF, and re-preview the book. This sounds tedious, and it is, but in the greater universe of book publishing, it's actually kind of amazing that you can do this from the comfort of your computer.

Ready? Not quite yet

Once you've set all the options and you've signed off on the preview version of your book, you're ready to go. Oh, wait! Not quite.

Before you finish-finish (contrastive-focus reduplication, it's in the book), you should proof your book. Order a proof copy and wait impatiently until it arrives. Then scrutinize it page by page, line by line. I guarantee that you'll find things you want to change. (If you're me, you'll still miss stuff.)

With your marked-up proof copy in hand, go back to the Word file for your print version and make the fixes. (You might even need to go back to the KDP version of your Word doc.) Then do all the review stuff again (don't forget to update the TOC) and save it as a PDF. Check the PDF. Re-upload the PDF to KDP and preview it there again.

Ok, now for real

When you've decided that your post-proof Word file is as perfect as you can make it (perfect used in a non-absolute sense, it's in the book), you're really ready. After you've uploaded the perfect version of your PDF file and previewed it, click Publish Your Paperback Book. Shortly thereafter your book will appear on Amazon.

Because the book is published on demand, and because they have to mail you the thing, it takes a while to get a copy. I think I waited about two weeks for my copies, but YMMV.

Linking book formats

A final note: when you have both a Kindle version and a print version of your book, you can link them in KDP. I believe that the effect is that Amazon has one listing for your book but shows both editions. Seems like a no-brainer, but you do have to explicitly do this.

Lessons and what's next

A few thoughts about what I'd do differently next time, and some things I might still do.

• (Possibly) Test the entire process first by publishing a shorter, easier book. I would have learned a lot by writing and publishing, say, a 30-page giveaway book.
• For some things, it would have been useful to start with the print version and then adapt that for the ebook version. Either way, though, there would still have been manual work in converting one to the other.
• Stay my hand with the footnotes. Those proved to be a lot of work, and as noted, in the print edition I ended up incorporating many of those notes back into the text anyway.
• Edit and proof even more. I went over the manuscript and the proof copy many times, and I still find stuff, oh well.
• Get someone to design a better cover. Especially I'd get someone who can create a PDF file with the front, back, and spine laid out per the KDP spec.
• Get my own ISBNs. That way I could publish the book on different platforms, not just Amazon.
• Professional book design?
• Index for the print version.

After thinking about it for a while, I think I'd do the same thing again that I did with links. For the ebook, I'd keep external and internal links and mark external ones. For the print book, I'd convert external links to footnotes and convert internal links to special formatting for print. I'm interested in other people's opinions about how to handle this.

Someone asked whether the book is available other than through Amazon, since some people don't like that platform. At the moment, no. I think I can make the book available on other self-publishing platforms based on the existing ebook and paperback manuscripts that I have. I'll need to investigate. Is the book available in a bookstore? Sadly, no.

And someday, I suppose, I'll get around to releasing the second edition. :)

Part 3 of a series about what I did to self-publish an ebook and then a paperback version of it.

• Part 1: The original manuscript
• Part 2: Formatting the Kindle ebook
• Part 3: Publishing the ebook (this entry)
• Part 4: Formatting and publishing the paperback

I mentioned earlier that I published using Kindle Direct Publishing (KDP). To do that, you create a KDP project in Kindle Create (KC), as I covered in Part 2. You create one project for your Kindle ebook. If you want, you can create additional projects for other formats, which I'll get to in Part 4.

To get through the KDP publish process, you need to create and decide on a few things. Here's what I cover in this entry.

• The book description
• ISBN
• Cover art
• Configuring KDP for publishing the ebook
• Keywords and categories
• Pricing
• Ready? Go

The book description

You must provide the text that Amazon uses on their site to describe your book, up to 4000 characters. It's probably a good idea to have that text ready to go when you start your KDP project. Here's where the description text shows up in Amazon:

ISBN

All books can have an International Standard Book Number (ISBN). (I could call this an ISBN number, which would be a redundant acronym phrase, as covered in my book, haha.) In the US, you can buy ISBNs from Bowker at $125 a pop or $295 for 10. Because each edition of your book—including ebook vs print—uses a different ISBN, the package deal seems like it could be useful.

Amazon says that Kindle books are not required to have an ISBN. Because I really wasn't sure what to do, I skipped the ISBN for my Kindle edition. For other formats, like paperback, Amazon will give you a free ISBN, and that's what I did for the print edition.

Important point: if you want your book to be available anyplace other than through Amazon, you must provide your own ISBNs. If I were doing this all over, I'd probably buy my ISBNs independently so that I could use them as I wanted.

You can read more about how ISBNs work and whether and how to get them in Publishing: Everything the Indie Author Needs to Know about ISBNs for Self-published Books.

Cover art

Even though you're publishing an ebook, you need to have cover art. The cover appears in your Amazon listing and in readers' Kindle libraries. Ideally, you'd probably hire a professional for your cover art. (I didn't, and it shows.) KDP wants you to upload a .tif or .jpg file that's (ideally) 2560 pixels high by 1,600 pixels wide. There's a page on the KDP site that provides some more details about cover art specification.

I got help from one of our art- and tech-savvy kids. I created the speech-bubble word cloud on wordcloud.com and exported that, and then Art Kid imported that into Canva.com and we did the rest there and then exported a high-quality JPEG file. (She was taking my lead, so the amateur-ish nature of the cover is not to be blamed on anyone but me.)

Anyway, have your cover art ready to go when you start your KDP project.

Configure KDP for publishing the ebook

When you've got your manuscript and other prerequisites sorted out, you go to the KDP site and sign in with your Amazon credentials. Then click the big yellow Create button to begin your project. This starts a multi-page configuration process.

You upload your cover art and content on the second page. For the text, you upload the .kpf file that you created with Kindle Create.

After you've uploaded the manuscript, you can preview the book. Even though you might have previewed the book in Kindle Create, KDP really wants you to preview the book during the configuration process. Launch the previewer and have a look. If you want to make changes, you go back to Kindle Create (or all the way back to your Word doc), make the change, and then re-upload the .kpf file. When you're happy with the book, then—gulp—click the accept button.

Keywords and categories

You can specify up to 7 keywords that describe your book. This is basically SEO-lite, I guess? I used the keywords language, vocabulary, and linguistics.

You also have to enter "browse categories" based on the existing categories that Amazon uses on its site. Because my book was about language, I ended up using these two categories:

Nonfiction > Language Arts & Disciplines > Linguistics > General
Nonfiction > Language Arts & Disciplines > General

Pricing

The last page of the KDP configuration is about sales and pricing: where to sell the book, how to sell it, and what to charge for it. This is confusing, because they give you a range of prices and royalties, and unless you've already studied up, you might not know how your choices here affect the availability of your book. I chose $9.99 because I got the sense that that's what Amazon was trying to get me to do. :)

Ready? Go

After you've finished the KDP configuration, you click Publish Your Kindle ebook, and you're done. Within a pretty short time (a day? less?), your book will be live on Amazon as a Kindle book and you can tell all your friends.

Up next, Part 4: Formatting and publishing the paperback

Part 2 of a series about what I did to self-publish an ebook and then a paperback version of it.

• Part 1: The original manuscript
• Part 2: Formatting the Kindle ebook (this entry)
• Part 3: Publishing the ebook
• Part 4: Formatting and publishing the paperback

When I began working on creating a Kindle version of the book, I duplicated my manuscript—I had the original Word doc and then a Kindle Direct Publishing (KDP) version of the Word doc, where I made all the Kindle-specific changes that I describe below. This meant that if I decided to make a content change, I had to make it in both documents.

Here's what I cover in this part:

• Some Kindle basics
• My problem with links and footnotes
• The Kinde Create tool
• Importing and applying styles and formatting
• Headings as chapter titles
• All other text
• Tables
• Graphics
• Previewing in KC
• When you're done with KC

Some Kindle basics

It helps to understand a couple of things about how Kindle works. (I'm not an expert, so bear with me.)

• Readers can pick a preferred typeface, font size, paragraph spacing, paragraph alignment (left, justified), and some other layout features. Being able to change these settings is one of the great features of reading ebooks, actually. This means that although you can set these things in the manuscript that you upload, readers might change them. That said, you can control a few formatting settings, like relative font size.
  
  
• A lot of Kindle e-reader devices don't support color, so color by itself isn't going to be significant for readers using those devices. You'll want to try to be sure that everything in your manuscript also works with a non-color display.
  
  
• People can switch between dark mode (light text on dark background) and light mode. One person noted that this was an issue with graphics—if someone is reading in dark mode, a light-colored graphic really pops out, sometimes in unpleasant ways. Spoiler: I have no solution to this issue.

My problem with links and footnotes

When I wrote my original manuscript, I did a few things that I had to ponder when converting to Kindle (and later to print):

• I had a lot of links to websites, i.e. external to the book.
• I had a lot of internal links, i.e. cross-references to other entries in the book.
• I had a lot of footnotes. Some were asides, some were additional information, some were … well, anyway, I had a lot of them.

I realized that a lot of people would be reading their Kindles offline—that is, in airplane mode. I wanted to make it clear to readers when a link was external, so that they didn't click it and then get the "You're offline, do you want to turn off airline mode?" message over and over. Therefore, in my KDP manuscript, I added a caret (^) to every single external link, like this:

I did this by hand, but the process was a little easier because in my Word file I used the Link Checker tool from AbleBits. Among other features, this tool produces a list of all the links, so that helped me home in on the external links.

Because the convention of using ^ after a link to mark it as external wasn't necessarily obvious to readers, I added a section in the introduction to the book (and only the ebook) that explained this convention. I did this although I don't think people read introductions, and I also feel fairly strongly that formatting shouldn't require explanation.

Footnotes introduced a different problem. The conversion tool for Kindle (see later) can handle footnotes fine. In fact, better than fine; it can generate footnotes that include Wikipedia-style back links to return you to where you clicked the footnote.

However, the converter turns footnotes in your Word file into endnotes in Kindle. Because I had over 100 footnotes (probably unwise), it would have meant an enormous section at the end of the book, and I didn't want that.

So I created chapter endnotes, in effect. In the Word doc, at the end of each chapter (i.e. each entry), I added the words "Note 1," "Note 2," etc. and then the text of the corresponding footnote. I restarted the note numbering for each entry, and I manually made sure the numbering was sequential in the text and in the footnotes. Then I used Word bookmarks and internal links to manually create the links to these chapter endnotes. I also manually created the backlinks to return to where the footnote was marked. This sounds confusing, but here's an example:

Needless to say, this was a lot of work, and somewhat error prone. More than once I questioned the wisdom of my approach and of footnotes generally. Nevertheless, that's what I did. (I can explain this process in more detail if you're interested.)

I'm pleased to say that this worked great. It imported perfectly into the Kindle book and has exactly the effect I wanted.

The Kindle Create tool

Amazon has a free tool that's a huge help for creating books: Kindle Create (hereinafter KC).

The tool lets you import a .doc/.docx file, fix up the formatting (with some limits), preview the result, and then create a file to submit for publishing. Although you can edit and format most text, you can't edit everything—for example, at the time I was using the tool, you couldn't make any changes in lists.

The tool also lets you create a title page, a table of contents (TOC), an Acknowledgments page, About the Author page, and so on. I had already created those in my original manuscript, so I didn't really take advantage of those features.

Importing and applying styles and formatting

The KC tool supports a modest selection of styles, which they call elements. These include Chapter Title, Subheading, Block Quote, and Body Text. These are fine for a lot of uses, such as novels.

Headings as chapter titles

When you import your Word file into KC, KC recognizes text that's styled as a heading (any heading, not just Heading 1 paragraphs) and marks those headings as Chapter Title elements. When the import process finishes, KC offers you suggested chapter titles that shows you everything that it thinks is a chapter title:

You really want to scrutinize this list and unselect the elements that are not real chapter titles. You should do this right at the beginning, because it's easier to do this now than to fix up the formatting later. When I did this, some of the non-heading paragraphs were marked as Chapter Title elements, I don't know why. I just unselected those as noted here.

All other text

As far as I can tell, anything other than a heading style from the Word file is imported as Body Text.

However, KC imports the formatting (as opposed to the style) of text in your Word document, up to a point. Kindle renders body text using the reader's choice for typeface and font size. Beyond that:

• Character formatting. KC imports italics, bold, color, underline, and other basic character formatting. It retains font sizes that you've applied, but not typefaces/font families. For example, because KC doesn't import font families, I don't know how to get it to import a monospace font like Courier or Consolas.
  
  
• Paragraph formatting. In my manuscript, the body text was aligned left; in other words, I didn't explicitly set alignment to center, right, or justified. When KC imported the text, paragraphs were justified, which is the Kindle default. (As noted, Kindle readers can change this.) During the import process, KC retains paragraph formatting such as line spacing and indentation. If you've aligned paragraphs center or right, KC retains that. If a paragraph has a non-default font size, the import process retains that, too. For example, I set the font size for my blockquote paragraphs to be 1 point smaller than for body text, and the import process respected that.
  
  
• Page breaks. Page breaks are retained.
  
  
• Links. Links in the Word file are imported as links in the Kindle format.

After you've imported the Word file, you can (mostly) manually edit and format text in KC. The formatting options are fairly rich: you can set font (including font face), color, bold, etc. For example, if you want to set some text to monospace, you can do that in KC with manual editing. For paragraphs, you can set indentation, spacing, and justification.

You can also "cascade" your format settings for the element you're playing with. (This is like CSS, or in Word, like making a change in Word to the style definition for that text.) For example, by default, KC renders all Chapter Title elements (headings) using all caps. However, you can select a heading (element: Chapter Title) and then set casing to UPPER CASE, lower case, Title Case, or None. I did this—I selected a heading, set casing to None, and then made sure that the Cascade formatting changes for elements option was selected:

This told KC to leave the casing of my headings as I had set them in the manuscript. Because I enabled the "cascade" option, it made this change to all my headings.

I mostly did not make text or formatting changes in KC (except for headings, see previous). Instead, when I wanted to change the formatting, I went back to the KDP version of my Word doc, changed formatting there, and then created a new KC project and re-imported my text. I ended up doing this many times—4? 6? 10? I forget. I did it however many it took me until I'd ironed out all the issues I found in KC and until could import a clean doc. I did this because I knew I was going to need to do further work in Word later and I wanted the changes to be in the Word doc.

Tables

My manuscript had several tables in it, but I'd read repeatedly that ebooks don't handle tables well. For small tables, I converted them to graphics. Here's an example of a small table that I converted to a graphic—I just took a screenshot of the table in the original manuscript:

A lesson I eventually learned here is that before you take the screenshot, make sure that the text of the table is perfect. And make sure that spell-check and grammar-check haven't left squiggly lines under words in your table.

For large tables, I didn't try to create graphics from them. Instead, I converted them into lists. In HTML terms, I emulated a description list, though I did that manually, not through styles.

Here's what one of those tables looked like originally:

And here's what I converted it to:

To do this, I created a special paragraph style for the terms and descriptions so that they'd be indented and so they'd have a smaller font size. I had to manually convert the original table to this new set of styles. But once I'd done that, the KC tool respected these formatting choices when it imported the text.

Still, lesson learned: if you know you're going to publish in an ebook format, stay away from tables.

Graphics

I had read that KC could import embedded graphics directly, and that was my experience. fwiw, I had only JPEG and PNG graphics.

KC imports any alt text that you've assigned to graphics in the Word file. But you can also write alt text in KC if you didn't do it in Word.

In KC, you can resize a graphic using t-shirt sizes: Small, Medium, Large, or Full. If you choose Large or Full, the graphic is centered. If you choose Small or Medium, you can also specify whether you want text to flow to the left or right of your image.

As I noted earlier, someone pointed out to me that graphics will pop out at them uncomfortable way if they're reading in dark mode. As of now, I have no answer to that issue.

Previewing in KC

The editing layout that you work with in KC is a pretty good approximation of what the text will look like. But KC also has a Preview mode that lets you get an exact sense of how the book will look like in different form factors. You can choose to preview in Kindle E-Reader, Tablet, or Phone device types.

When you're done with KC

When you've got your text done in KC, you save your project as a .kpf file. That's the format you use for the next stage, which is to set up your Kindle book for publishing.

Up next, Part 3: Publishing the ebook

I self-published a book recently. (Crash Blossoms, Eggcorns, Mondegreens & Mountweazels: 101 Terms About Language That You Didn't Know You Needed) I used Kindle Direct Publishing (KDP), which lets you set up and then publish Kindle ebooks, paperbacks, and hardbacks. The print versions are print-on-demand.

I learned a few things about the process (by no means everything), so I thought I'd capture so that I have a reference for the next time I decide to do this. :)

I've done this in a multi-part blog post series.

• Part 1: The original manuscript (this entry)
• Part 2: Formatting the Kindle ebook
• Part 3: Publishing the ebook
• Part 4: Formatting and publishing the paperback

A couple of the individual parts are sort of long, sorry. I didn't want to split them up any more than this, though. Here's what's in this first part:

• The Word file
• Using styles
• Paragraph styles
• Character styles
• General formatting

The Word file

I wrote the manuscript in Microsoft Word. For better or worse, Word files (.doc, .docx) are a (the?) favored format for importing into the KDP pipeline.

Using styles

My advice is that if you're intending to publish to both Kindle and as a print book (paperback or hardback), use styles in Microsoft Word. As I'll explain later, this will make it easy for you to convert things like headings for the Kindle, and to convert hyperlinks into something else in the print editions.

For most publishing needs (fiction, say), it's probably sufficient to use styles for headings and body text. I wanted to use some special formatting, so I created custom styles. (I love styles.) In the sections that follow, I have a short list of the styles I created. These are specific to my scenario, which is a non-fiction book; I'm not suggesting that you follow this lead. If you're not a style nerd, skip to the General formatting section later.

Paragraph styles

Normal. The body text for my book was all in the Normal style. For the original manuscript, it doesn't really matter what your style settings are. The settings for your Normal style don't become important till you're formatting for print, which I'll explain when I get that far.

Example. I wanted a special style for paragraphs that were for examples. I defined this style as .25 inch indent, non-default paragraph spacing. In my manuscript, I had this as a contrasting (sans serif) typeface—that didn't matter for the ebook, but it did later for the print book.

Blockquote. I created a different paragraph style for when I had a longish cite from another source. This was indented, and it used the default typeface, but 1 point smaller.

Related terms list. At the end of each entry I have a "Related terms" heading followed by a paragraph that lists related terms in the book. I wanted to be able to control the formatting of this list independently of the body text. This ended up helping a little later for the print edition.

Character styles

I really went to town on character styles, many more than I needed. A couple of notes about character styles.

Word as word. I created a character style for when I wanted to call out a term that I was talking about. This renders in the default font and in italics.

Word as word emphasis. This style was for when I wanted to call out an individual part within a word-as-word. This renders as italics + bold.

Example emphasis. A style for calling out something within an example. This uses the same font that I used for the Example paragraph style, plus italics + bold.

Hyperlink. I had links in my manuscript, both external links (to websites) and internal ones (to other sections of the document). When you create a link in Word, it styles the link as Hyperlink (blue + underline). It became important later to be able to work with this style.

As I say, I had many styles. You can see that a lot of the character styles end up rendering the same: italics, bold, italics + bold, etc. This is generally true of character styles—there are a limited number of ways that you can format words. Still, it's useful to have "semantic" styles: styles based on the purpose of the formatting, as opposed to what the text looks like.

Using semantic styles did end up being beneficial. For the most part, the look of the text didn't matter much for the ebook—Kindle has its own ideas about how to render text. (Some of the styling information translated to the ebook when I exported it to Kindle, as I'll eventually explain.) Styles were particularly useful later when I formatted the book for print—when I was laying out the print version, using styles made it easy to change my mind about how I wanted things to look in print. That said, I would have been okay with fewer character styles and with using direct formatting for the few oddball instances.

General formatting

In addition to formatting using styles, I did the following formatting.

Non-breaking spaces. I added non-breaking spaces when I wanted a space but didn't want Word to break a line before or after a piece of punctuation.

Non-breaking hyphens. I used non-breaking hyphens when I didn't want Word to break a line before the hyphen:

So that's what I did in the Word manuscript. In the next installment, I'll talk about how I worked with the Kindle Direct Publishing tools to prepare my manuscript as an ebook.

Up next, Part 2: Formatting the Kindle ebook

A couple of weeks ago I sat down at my main home computer and was greeted with the message “No bootable device.” Uh-oh. I’ve had this old HP desktop for something like 9 years. About 5 years ago I swapped the ailing hard drive for a solid-state drive (SSD), which had been working great.

One of my colleagues pointed out ominously that SSDs tend to fail catastrophically; you don’t get a couple of days or weeks of squeaks or other alarming noises, the way you usually got when an old-style hard drive was ailing. I had some dim hopes that maybe the issue was that it was a BIOS problem, and that the issue was just that the computer had lost its memory and forgotten that there was an SSD attached via SATA.

Alas, no. I took it to a guy who confirmed that the SSD drive could not be read, not even for ready money. He also pointed out that my computer was quite old, something I already knew—Windows had given up on urging me to update to Windows 11.

New box

So, new computer. This gave me pause. Since 1987 or thereabouts, I’ve always had a desktop computer tucked under my home desk, and then later a separate laptop for mobile use.[1] But did I need that anymore? I guess not. I have only a laptop for work and have learned the wonders of using hubs to attach all the peripherals—big keyboard, external mouse, monitors, etc. Laptop as a Desktop (LaaD), haha. So I ordered a ThinkPad, a solid laptop for business, and I’m going to see if I can do everything from now on using a single mobile computer.[2]

The new computer is nice enough; I mean, it runs Windows 11. Plug-and-play works very well. I haven’t even had to think about drivers, including for my external monitors and printer. I don’t want to jinx it or anything, but so far “it just works.”

But I am of course faced with the task of reconstructing what I had on my old computer. This has been a bit daunting.

Did I lose data?

The most pressing question was what data I might have lost. On the old box, I’d managed this in a number of ways:

• A program (iDrive) that performed an ongoing backup to the cloud of the folders I told it to back up.
• Auto-synced folders (Dropbox, OneDrive, and Google Drive) whose contents were copied to the cloud.
• A scheduled script that backed up my Word templates (e.g. Normal.dotm).
• Copies of some stuff that I had on my Yoga laptop.

My conclusion is that I think I still have most of the data. I say “think” because for sure there were some folders that were not auto-synced and not included in the iDrive backup, but of course I don’t remember (and cannot look up) what those might have been. I imagine that over the weeks and months I’ll ask myself “Didn’t I used to have a file with <thing>?” and wonder whether it was lost in the disk failure.

All those installed programs

My backup wasn’t a disk image, just data, so it couldn’t restore applications that I’d installed.[3] This meant that I was going to have to reinstall all the apps that I use. I was not looking forward to this. I also knew that I’d lost some programs that I could never recover. For example, I’ve been nursing a truly ancient edition of Photoshop Elements that I still used occasionally. Sad.

Windows 11 surprised me pleasantly by recognizing that I was on a new computer and offering to reinstall anything that I’d gotten previously through the Microsoft Store. That wasn’t a huge number of programs, but it did include Microsoft Office, so that was one less thing to worry about.

I don’t have an inventory of everything I’d ever installed on my old computer. I expect the process of reinstalling to be ongoing, and in the weeks to come I imagine myself reaching for some utility that I’ve used and remembering that oops, that’s not installed on this box.

As I said, a lot of the data I had was on synced drives like Dropbox. But to get to that data, and to mirror it back to the new computer, I needed to install password-protected apps like Dropbox. Which brought up the issue of passwords.

Bootstrapping security

To access or reinstall programs, I needed a lot of passwords. I use a password manager, so I had to bootstrap that: I had to install the password manager first so that I would have access to all the passwords I’d need for everything else. To do this, I went to the website for the password manager and signed in. Did I have the password for that? Yes. (Whew) That let me install the password manager app and the Chrome extension, which in turn helped me get logged in to many other sites that I was going to need.

I also occasionally needed product codes. I also had copies of those, thank goodness. (You probably can recover product codes from the product website, assuming you have the password, but it wasn’t an issue for me.)

On the plus side, once I’d logged in to my Google account, all my Chrome bookmarks were synced. Same with my Microsoft account and Edge and Office.

Re-logging in to all my many and various accounts meant that I got tons and tons of requests to use two-factor authentication—my Yubico key got a real workout, and I got a lot of SMS messages with one-time passwords. I also got tons of emails alerting to me to new logins from an unknown computer. This is all expected and I’m thumbs-up on 2FA and notifications, but dang, there were a lot of them.

Some lessons for me

This type of event should be a learning experience, right? Here are some things I think I’ve learned:

• Sync everything to the cloud? Should I keep all my data in auto-synced folders? I haven’t completely thought this through—like, do I want everything on the cloud?—but I’m leaning that way right now.
• Keep copies of important keys. Kee a copy of passwords and product keys somewhere “safe,” i.e. off the machine. (Maybe not in the cloud, and definitely not on sticky notes on your monitor.)
• One laptop to rule them all. It might just be possible for me to wave bye-bye to my Era of Desktops. But …
• Do I even need a laptop-laptop? As noted, the important stuff seems to have been preserved in the cloud. These days I’m constantly using cloud-based apps (Google Docs, etc.). Would it make sense for me to use a Chromebook equivalent? I thought about this, but my conclusion for now is that I’m not ready to have a computer that requires an always-on connection. And I still like the installed (as opposed to web-based) apps like Office.

One result of starting over with a clean SSD (I hesitate to call this a “benefit”) is that it could inspire me to organize my storage differently. In the past, whenever I’d gotten a new computer or a new disk, I would just copy everything over as is. This habit perpetuated a lot of cruft—duplicated files, duplicated folders, related information scattered in different places, and tons of old stuff. (Those teaching files from 2009? Maybe I can purge those.)

It hasn’t been a, you know, fun experience to be forced to get a new computer and configure it. I can say that the process has not been as bad as it could have been, had I not had synced folders and so on. I’m sure I will continue to have pangs of regret about something or other that appears to have been lost. And hopefully It’s not an experience I’ll have to revisit too terribly soon.

I was sharing all this with my friend Alan, with whom I’ve spent some quality time in the computer business. His response: “Remember when it was exciting to get a new computer?”

[1] Insert that observation about how desktops are not on top of the desk, and laptops are not on the lap.

[2] Side note: no touchscreen for me. The last laptop I got was a Lenovo Yoga, but I didn’t use the touchscreen much, and then it cracked anyway, and I never missed it.

[3] I’m not entirely sure that you can restore a disk image between unlike computers and different versions of the operating system. For me, of course, the issue is moot.

On Twitter recently, DeAnna Burghart reminded us that if you use Microsoft Word, it's important to back up your Normal.dotm file. If the file is overwritten or corrupted, you lose your macros, your keyboard shortcuts, and other goodies that editors rely on.

I've experienced that problem, gah. So a while back, I set up Windows so that it automatically backs up my Normal.dotm file several times a day. I thought it might be useful to show other people how I did this.

Sad note: The information in this post applies only to Windows. I'm sure there's a way to do this on the Mac, but I don't currently know how to do it.

I realize that this is a long post and therefore looks complicated. It isn't, I promise! I added some extra steps to test as you go to try to make sure that you don't Experience Disappointment.

• Background
• Create the PowerShell script
• Test the script
• Schedule the backup
• Test the scheduled task

Update: I created a video version of this tutorial!

Background

To back up your Normal.dotm file, you copy it from its default location (i.e., where Word looks for it) to some other location. AFAIK, the default location is always this:

DRIVE:\Users\YOUR-USER-NAME\AppData\Roaming\Microsoft\Templates

C:\Users\Mike\AppData\Roaming\Microsoft\Templates

You can certainly copy the file manually. But you can also automate the copy process so that Windows copies the file for you. You might sometimes forget to back up your file by hand, but if you automate the process, you never need to worry about it.

What I did—and what I'll show you here—is that I created a script. The script doesn't just copy the Normal.dotm file to another folder. During the copy process, it names the backup file by adding a date and time stamp. For example, the script creates a file that has a name like this:

Normal(2021-04-26 17_49).dotm

You can see that the filename includes the date (Apr 26, 2021) and time (5:49 pm). Timestamping the backup files has two advantages:

• Each time you run the backup, you make a new, different backup file. This can be useful if Normal.dotm gets corrupted—you have multiple backup versions of the file, some of which (hopefully) are older than when the corruption occurred.
• You know when the backup was made.

I use two technologies for the automated backup:

• PowerShell. This is a programming language that lets you automate Windows tasks like copying files. PowerShell has been in Windows since Windows 7, so you don't need to install anything. I have the complete script in this post, so you don't need to know PowerShell; you can just copy and paste the script.
• Windows Task Scheduler. This is a Windows utility that lets you run tasks—for example, a script—at specific times or at intervals.

Create the PowerShell script

1. Create a folder named C:\backup on your computer to copy the backup files to.

   You don't have to use this folder; you can use any folder you like. Just make sure that the folder already exists. (The script won't create it.) If you don't use C:\backup, you need to make some minor changes later.

2. Open a text editor (for example, Notepad ... don't use Word for this), create a new file, and then copy the following script into it:

   # PowerShell script to back up the Word Normal template (Normal.dotm)
   # 2020-Apr-26 Mike Pope
   
   $bu_path = "C:\backup"
   
   $bu_datetime = Get-Date -Format "yyyy-MM-dd HH_mm"
   $source_file = $env:appdata + "\Microsoft\Templates\Normal.dotm"
   $dest_filename = $bu_path + "\Normal(" + $bu_datetime + ").dotm"
   Write-Output $dest_filename
   Copy-Item -Path $source_file -Destination $dest_filename

3. If you don't want to use the C:\backup folder, change the path in the third line (the one that starts with $bu_path =). Make sure that you don't add a trailing backslash (\) to your path.
4. Save the file to the C:\backup folder (or your alternative) using the following name:

   back-up-normal-template.ps1

   The .ps1 extension is used for PowerShell scripts.

5. Close the text editor.

Test the script

Before you create a scheduled task for the script, it's a good idea to make sure it's working on your computer.

1. Open a Windows command window. (Press Windows+s, then type CMD). You see a command line:

   

2. Enter the following command (better yet, copy and paste it):

powershell.exe -ExecutionPolicy Bypass -File "C:\backup\back-up-normal-template.ps1"

Again, if you're not using C:\backup, substitute your folder name.

The command invokes PowerShell and tells it to run the script that's in the back-up-normal-template.ps1 file that you created earlier. The ExecutionPolicy argument tells PowerShell that your script is safe; if you don't include this part, PowerShell will refuse to run the script due to security concerns.



If all goes well, the script displays the name of the backup file, like this:

C:\backup\Normal(2021-04-26 17_59).dotm

If you see red text, read it carefully. Carefully check the command that you entered. You might also need to fix the script itself (the .ps1 file). Some possibilities:

• The script you used earlier assumes that the Normal.dotm file is in the default location. If the file is in a different location, it's possible the script isn't finding it.
• If you're not using the C:\backup folder, did you fix up the script to reflect the folder that you are using?

You must resolve any errors before you can proceed.

3. If the script appeared to run correctly, look in the C:\backup folder (or the folder you are using instead). Do you see a .dotm file that starts with Normal followed by a date and time? If so, everything is working.

Schedule the backup

You can now configure Windows to run your script at intervals. You do this by creating a scheduled task. When you create the task, you specify what you want to run (the PowerShell command that you just tested) and when you want to run it.

1. Open the Task Scheduler app. (Press Windows+S, then type Task Scheduler.)

2. In the folder tree on the left, right-click Task Scheduler Library and then click New Folder. Name the new folder My Tasks. This step isn't essential, but it makes it easier for you to find your custom task later if you want to modify it.

   

3. Right-click the My Tasks folder and click Create Task. This opens the Create Task dialog, which has several tabs that you'll be working in.

   Note: Don't close the Create Task dialog (that is, don't click OK), until you've done all the steps.

4. In the General tab, do the following:

   1. In the Name box, enter the name BackupNormalTemplate.

   2. In the Description box, enter details about what this task is about.

      

5. Go to the Actions tab and click New. This is where you specify what you want to run—namely, the PowerShell script.

   1. In the Program/script box, enter powershell.exe.

   2. In the Add arguments box, enter the following:

      -ExecutionPolicy Bypass -File "C:\backup\back-up-normal-template.ps1"

      These settings specify that you want to run the PowerShell script that you tested at the command line earlier.

      

   3. Click OK to close the New Action dialog and return to the Create Task dialog.

6. Go to the Triggers tab and click New. This is where you specify when (how often) to run your script.

   1. Under Advanced settings, select the checkbox next to Repeat task every.

   2. Enter an interval for how often you want to run the script. For example, to run the script twice a day, enter 12 hours. (It doesn't look like it, but you can type in that box.)

   3. In the for a duration of list, choose Indefinitely. This tells Windows to keep running the script until you change the interval or delete the scheduled task.

      

7. Click OK to close the New Trigger dialog.

8. In the Create Task dialog box, click OK.

Note: Don't close the Task Scheduler window yet.

Test the scheduled task

You know that the script runs; now you want to make sure that the scheduled task works.

1. In the Task Scheduler, in the file tree, click the MyTasks folder. The list of scripts in that folder is displayed on the right.



2. In the right-hand pane, right-click the BackupNormalTemplate task and then click Run.

   

   The PowerShell scripting window appears briefly, then vanishes.

3. Go to the C:\backup folder and check that another backup copy of the Normal.dotm file has been saved.

   If this worked, you should be all set.

   

4. Close the Task Scheduler app.

You probably want to check the C:\backup folder tomorrow and the next day to make sure that the script is writing out backup files at regular intervals.

If you need to recover a Normal.dotm file, go to the C:\backup folder, rename one of the backup files to just Normal.dotm, and then copy it back to the folder where Word keeps the template.

Hopefully you'll never need to do that. But if you do, you'll have a recent backup available!

I was listening to a podcast yesterday when it was interrupted with an ad that started like this:

Do you have 30 minutes to spare? Because after just one half hour, you'll never have to worry about a break-in at home again. That's how easy it is to set up a security system from [company name].

My editor brain froze at the point. What I heard was a claim that if you installed their system, you would not be broken into—you would be protected against burglary forever ("never have to worry").

When we technical-edit documents at work, one of our priorities is to check for what we call overclaiming. For example, we stay on the lookout for instances of overclaiming about security, like this:

This product prevents bad actors from hacking your system.

A claim like this simply can't be guaranteed. In the realm of security, the apparent strength of your product might just mean that a hacker hasn't found a flaw in it yet. For example, encryption algorithms that once seemed secure enough to be used by the NSA have been cracked.

We look for overclaiming in any discussion of performance:

Using this product makes your applications three times faster.

We look for it in mentions of costs:

This product reduces your computing costs by 50 percent.

For performance claims, we warn authors that anything that states a number has to have data to back it up. If you say your product is three times faster, you better be able to produce the tests that show this. The same applies to any mention of costs: numbers, please.

And we look for it in any text that involves comparison to other products:

Our product is substantially easier to use than [competitive product].

This claim is problematic in multiple ways. First, what does "easier" even mean? Something that's easy for me might be hard for you and vice versa. And competitive products are a moving target anyway; perhaps our product is "easier" than the current version of product X, but who knows what's in their next release.

So naturally I stumbled over "you'll never have to worry about a break-in at home again." But I thought about it for a bit. First, it's advertising copy, not a technical document on how to configure cloud computing. Maybe there's more wiggle room for wild claims, as in, people aren't expected to interpret these things literally.

I also homed in on the phrase "worry about." With some work, this can be made ambiguous. One idiomatic interpretation is that it means that something won't occur:

A more literal interpretation is that, well, you don't need to worry. This is the type of messaging that insurance companies use: it's not that [thing] won't happen, it's that you can stop worrying about [thing] happening because insurance.

I have a hard time fitting this second meaning onto the ad copy for home security systems. But if I had to defend that statement in court, say, that's what I'd go with.

Speaking of consequences, all of this hypervigilance about overclaiming is of course ultimately about protecting the company. The fear is not just that we'll be shown to have been wrong. ("Sorry.") When people spend vast sums based on assurances that you've given them about security or performance or cost, and when those assurances don't prove true, they might take a litigious turn of mind. At the very least, they're not going to trust you in the future and might look elsewhere to spend their money.

I'm not personally aware of the various companies I've worked for being hauled into court to defend an assertion. ("You said we wouldn't be hacked!") But clearly the lawyercats think about this a lot, and I've certainly participated in my share of fire drills in which we dropped everything to grub through many documents, tweaking some text that was discovered to be overclaim-y.

I would not be surprised to hear an ad from the same company a year from now in which the claim "you don't need to worry about break-ins" has been hedged to something like "Get yourself some peace of mind." If I were editing their copy, that's definitely what would happen.

Over the weekend I ran a security check on my computer. One of the startling results was the report by my password manager that I had many dozens of "compromised passwords."

After my pulse returned to something resembling normal, I looked a little more closely at the report. What they were not saying, I had to figure out, was that dozens of my accounts had been compromised. They only meant that the password that my password manager is storing for some websites was among the passwords found in someone's data breach.

I looked through the list of affected websites in my password manager and had an Aha! moment: virtually all of them are sites where I use a "throwaway" password. That is, I'm interacting with a site and they insist that I create an account, and I end up using the same password over and over. For example, I've done this for some sites that I intend to visit only once.

This is a bad idea, and I should know better. Reusing passwords is a big security risk.

Think about how this works: you use the same username and your throwaway password for a number of sites. One of the sites is breached, and your password and username fall into the hands of people with mal intent. These people then try your username+password combination on hundreds or thousands of sites. In my case, for example, they could have gotten access to dozens of sites that way.

I like to think that I've reused my throwaway password benignly, only for "unimportant" sites. But I can see in retrospect that even if the sites have no commercial value, someone could impersonate me on those sites and do some sort of mischief.

But I think we can also imagine many people using the same password not just for benign sites, but for important sites. This is one way that people's social media accounts get hacked.

So, in part for my own benefit, let's review some security practices that everyone (me, too) should be following:

Don't use the same password on different sites. As explained earlier.

Use a strong password. A strong password is one that's long and random. It doesn't mean just substituting numbers or punctuation in a word (like S3att!e). A decent approach is to use a passphrase rather than password: not just a string of characters, but a string of words. The longer the phrase, the more "entropy" it was, meaning that it's harder to crack. Many people know the xkcd cartoon that explained this beautifully:

Of course, the site has to allow this. A surprising number of sites still prohibit spaces or have a too-short maximum password length. And the "strong test" that some sites show you as you're creating a password isn't necessarily very good, so don't take their word for it.

Use a password manager. One reason people reuse passwords is so they can remember them. Use strong passwords, as noted, and then let a password manager do the remembering. You just have to remember one password, namely the one for the password manager. (Use a strong password for that, please.)

Among 2FA options, a good one is a hardware key, like those offered by Yubico. For this, you have a little thing that looks like a USB dongle; as part of your login, you have to touch the key. Hardware keys aren't supported on many sites yet, but you can use them on some important ones, including Gmail. (Full disclosure: we use hardware keys at work.)

Use security questions wisely. In 2008, Sarah Palin was famously hacked by someone who got answers to her security questions by studying her biographical data. The answers to your security questions are probably not that hard to find either—for example, how fast do you think someone can discover your mother's maiden name or your high school mascot? (Many social-media questions and polls seem designed to solicit information that can be used to answer security questions.)

If a site insists that you have to set up security questions, you can create answers that are meaningful to you but that aren't easily guessable. As the simplest possible approach, just lie. Just remember what your lies are. :) A more sophisticated approach is to devise an algorithm for yourself that you always use. For example, maybe you take the first letters of the question and use those as an answer. If the question is "What is your mother's maiden name?," your answer could be WIYMMN. (Don't use this particular algorithm, please.) Or you do something with numbers or whatever. The idea is just to have something that you can reproduce many months hence but that isn't guessable.

Get rid of accounts you're not using. Did you set up an account on Pinterest or Coursera or the Los Angeles Times but you never use it? Delete the account. No password worries then for that account.

And finally, lock down your main email account as tightly as possible. When there are changes to your accounts, like a password change, you often have to confirm them via email. But if your email account has already been compromised, the game is up.

I guess I'll also note that I don't let websites store my credit card number. The only company I really trust is Amazon, in part because during my time there, I was impressed with the level of paranoia that they have about security issues, haha. But if J. Random Website offers to store my credit card info, no thanks.

If you want more details on all of this, I highly recommend a whitepaper written by a couple of the solutions architects at work: Modern password security for users (PDF). They have great ideas about strong passwords, about how to handle security questions, etc.

In an effort to improve my sleep regimen, I was recently prescribed a CPAP machine. This device helps with obstructive sleep apnea, where your throat closes during sleep. The CPAP machine basically pushes air into your nose and/or mouth to keep things open.

The concept is relatively simple, but it involves technology. You wear a mask; the mask is connected via a hose to the device itself, which blows air and has sensors to adjust the pressure and temperature. There's a water reservoir so the machine can humidify the air it's blowing at you. There are air filters that need to be changed periodically. The mask, hose, and water reservoirs need to be washed regularly.

So how does the manufacturer (Philips) make and distribute a machine that's a this complex but is intended for a wide variety of people? I count four ways, and am wondering about a fifth.

First, before you can take home your CPAP machine, you get a 20-minute training session slash demo. The trainer walks you how to assemble and use the machine, and they give you the schedule and some tips for cleaning.

I read once that people retain 10% of what they hear during a presentation. The exact number (10%) isn't that important; the idea is just that people don't retain everything you tell them.[1] And I think about all the people who use a CPAP machine. Is a 20-minute demo going to be enough to train this wide range of people? My guess is no.

So second, the machine comes with a manual—two, in fact, a quickstart and a detailed manual. These reiterate a lot of what you learn in the presentation, so you have at least the possibility of hearing it all twice. The quickstart has a lot of pictures. (The manual, a few line drawings.) For me, it was an interesting case of reading documentation for something that I felt I kind of already knew but that I needed some refreshing on.

A third way that Philips tries to help their users is through design. For example, when things connect, they go together in only one way. There's only one way to plug in the machine. The hose goes into the machine only one way. The filters and water reservoir go into the machine only one way; you can't close it if they're not right. The nosepiece in the mask has clear markings right on it for how to put it together. These are all versions of self-documenting features: you literally do not need to read the manual to understand how to put together the components.

As another example, there are very few controls on the machine. For basic use, you need to press only a single button to turn the machine on and the same button again to turn it off. There's a second button if you want to adjust the "ramp"—that is, to set the air pressure to increase gradually when you start up the machine.[2]

And there is a fourth way in which Philips can help people. The machine phones home to report a bunch of statistics about the user's sleep. (That part of the machine required no setup at all, which was great.) This feature has several purposes (some of them a little uncomfortable to contemplate), but at least if the distributor is getting odd reports or no reports from the patient, they know something went wrong. Perhaps they contact you if that's the case.

I imagine that with these efforts on Philips's part, most people can manage to put on their mask and get the machine running. But how well Philips does attempt to help users with ongoing maintenance? It's easy to forget to fill the reservoir. Similarly, the training emphasized that you should wash the hose every week. Is everyone really going to do that? I mean, we're all supposed to floss every day, but how many people really do that?

So I wonder. Does the machine stop and display a message if the water reservoir is empty? Does it tell you when it's time to change an air filter? Does it (somehow) figure out that it's time to wash the hose? I don't know, and I'm reluctant to get into a situation where the machine has to tell me these things. But given the many ways in which the machine, once running, can go wrong, I hope that the manufacturer has taken steps to try to keep it going.

All in all, giving out a complex piece of technology to people and expecting them to all use it right is a hard problem. It's clear that the folks at Philips have thought a lot about this and come up with different ways to try to handle it. Still, I am curious how many people fail when trying to use the machine—they never figure out how to use it, they use it wrong, or they don't maintain it and the machine itself fails. As someone with a professional interest in communicating complex concepts, I find this to be an interesting challenge.

[1] Someone on my team at work has a variant on this idea: you need to hear something 7 times before you learn it. ^

[2] There is also a dial that you can use to make a bunch of other settings, and the dial is multi-modal: turn left for one mode, turn right for another mode, and push for a third mode. Arg. I hate multi-modal controls. But at least this one is optional after you've done the initial setup. ^