mike's web log

It was twenty years ago today ...

Tue, 27 Jun 2023 08:16:48 GMT

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!

[more]

Publishing a Kindle book, Part 4: Formatting and publishing the paperback

Mon, 22 May 2023 16:34:10 GMT

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

[more]

Publishing a Kindle book, Part 3: Publishing the ebook

Mon, 22 May 2023 15:15:09 GMT

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:

[more]

Publishing a Kindle book, Part 2: Formatting the Kindle ebook

Mon, 22 May 2023 15:10:55 GMT

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.)

[more]

Publishing a Kindle book, Part 1: The original manuscript

Mon, 22 May 2023 13:39:08 GMT

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

[more]

To screenshot or not to screenshot?

Sun, 10 Apr 2022 21:38:09 GMT

When we talk to users about software documentation, we consistently get feedback that they like having screenshots in the docs. But screenshots are a conundrum for a technical writer because they introduce issues for the writer—issues that don't necessarily affect any one reader, but that can reduce the quality of the user experience over time and that have other meta implications. In fact, I'd say that screenshots are a documentation feature where the interests of the reader and writer can be quite at odds, as I'll explain.

Pros of screenshots
Cons of screenshots
Advice for using screenshots

Pros of screenshots

You probably know the advantages of including screenshots in documentation, but let's review. Screenshots have the following benefits:

Orientation. A screenshot can help the reader understand the layout of a console or window that’s in front of them.
Compact information. This is the "picture is worth a thousand words" benefit—a screenshot can save the reader from having to read a lot of words. For example, a screenshot can show a computer form with all the values already filled in that the writer otherwise has to describe in text.
Signposting. A screenshot can reassure the reader that they've done something correctly—"when you're done, it looks like this." A corollary is that if the user isn't [more]

Why random formatting isn't a good idea

Mon, 13 Sep 2021 15:22:09 GMT

Not long ago, one of the editors at work raised a question in our editing group: do we have any guidance about bolding parts of a sentence in a paragraph? Like this:

The editor asked the author why they wanted to bold things this way. "So they'll stand out visually!" was the reply, or something close to that.

We don't have explicit guidance in our style guide that says "don't bold parts of a sentence just for visual accent," so there wasn't anything we could point the author to. Nonetheless, I've been thinking about this question, and I want to articulate why adding random bolding is not a good idea.

First, formatting "has semantics," as we say at work—when something is italicized or bolded or capitalized or monospace, it conveys information to the reader. Our style guide has guidelines for when we use different types of formatting. For example:

Use bold formatting for UI elements and at the beginning of notices.

Use italics formatting when drawing attention to a specific word or phrase, such as when defining terms or using words as words.

(UI elements means that the text references a button caption or textbox label. Beginning of notices means words like Note: at the start of a note.)

By being very consistent with these guidelines, we help the reader understand not just the words in a sentence, but what their significance is. When a reader sees "Click OK," they know that the bolded OK refers to a button.

[more]

The hazards of overclaiming

Mon, 15 Mar 2021 08:54:25 GMT

The hazards of overclaiming

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.

[more]

More dubious guidance, reclining edition

Mon, 27 Jul 2020 12:16:57 GMT

Over the weekend, I bought a recliner at Costco, which my wife laughingly suggested was my admission that I'm an Old Guy. But before I could, you know, recline, I needed to assemble the chair and figure out how to work it. In our modern era, reclining chairs are electronic, which means there are 5 different controls, which in turn means that there is an instruction manual.

The manual has instructions for how to perform the one required assembly step, although tbh I had figured out how to do that without the instructions. There are also pictures of how to plug in the two (!) electronic connections, though again, these were self-evident and had also been designed so they could be plugged in only one way.

The useful part of the instructions was the diagram that showed what the buttons on the control panel do. Ironically, this illustration is very small for, you know, Old Guys. This is it to scale as best I can render it (2 inches wide):

A curious part of the manual is that whoever created the manual decided that they needed to cast the instructions as a set of numbered procedures. Here's step 2, which is one of the more forced applications of a numbered procedure step that I've seen.

Where is step 1, you ask? I'm saving the best part for last. Step 1 concerns a feature of the recliner that I had not previously thought needed instructing:

("While seated in the recliner, enjoy the rock feature which allows you to gently rock backward and forward.")

There's a lot of fun stuff to unpack here:

It's step 1.
[more]

A beef with cloud metaphors

Sat, 04 Jul 2020 10:42:28 GMT

One of the effects of this year's protests is that it has brought about heightened consciousness about language and how it affects or reflects certain thinking. For example, there have been discussions in the editorial community about capitalizing the word Black "in a racial, ethnic or cultural sense."

In the world of IT, we've been discussing the implications of certain terms for a while. The Microsoft style guide has suggested for a over a decade that writers avoid the terms whitelist and blacklist in order to avoid a connotation that white==good and black==bad. (I wrote about this a while back.)

Our own style guide has a section on inclusive language, and it suggests finding alternatives to a range of language that, when you look at it consciously, can have negative connotations or the possibility of offense. In addition to disrecommending the word blacklist, we tell our authors to use alternatives to terms like crippled system, dummy variables, sanity checks, native features, and first-class citizen.

A short digression about cloud technology. (For tl;dr, you can skip [more]

"Fewer your words": advice, not fetish

Mon, 13 Apr 2020 09:24:02 GMT

"Fewer your words": advice, not fetish

A couple of weeks ago, a (virtual) discussion broke out among the writers at work about "empty words" and how these should be eliminated. The original posting was about removing phrases like allows you to, helps you to, is intended for, and some others.

The topic generated a lot of interest, and people came to the conversation with different perspectives. One person: "Fluff should be eliminated." Another: More words make it that much harder for people who use assistive devices like screen readers.

You'd think that as an editor, I'd be delighted to see such keen interest among writers in the topic of "fewering your words," as we editors like to joke. There was a lot of advice that seemed helpful. And there were some nuanced points about reducing text too much.

But a number of issues came up that rubbed me the wrong way. I had to think about why that was, and I thought I should write down what I found.

The first thing that bugged me was a suggestion that we could train a machine-learning tool to eliminate these "unnecessary words." The proposer suggested that if there were a large enough training set that showed the work of human editors, this would be a good approach for suggesting changes. And I thought, how do you think grammar checkers work now?

Another thing that bothered me in the conversation was the confident assertion of absolutes. "The phrase in order to is never necessary," was one opinion. Hard disagree, as I explained a while back in the blog post "In order" to clarify meaning.[1]

For that matter, the original assertion that phrases like allows you to, helps you to, and [more]

Readability and pharma instructions

Mon, 06 Jan 2020 07:09:52 GMT

My life has been blessedly free of the need for pharmacological intervention, but I recently went for a checkup and left with a fistful of prescriptions. Because this routine drug-taking was sort of new to me, I actually read the inserts that came with the several prescriptions because, well, perhaps there was something I needed to know.

The text was hard for me to read, but that was only because it was in such small print—8 points, perhaps less. And there was quite a lot of it. But this technological limitation at aside, I was surprised at how readable the words themselves proved to be. Perhaps—and this is my observation—by design?

Some details. There are about 1230 words in all, which is about two and a half pages. The text is printed in blobs, aka “walls of text.” The only formatting is ALL CAPS and ALL CAPS IN BOLD. The text is not laid out with an eye to scannability. You can get an idea from the following, with a US quarter coin (about 1 inch/24 mm) for scale.

But as I read the text, I noticed that it seems written for clarity. Here’s an example:

Use this drug as ordered by your doctor. Read all information given to you. Follow all instructions closely. Take this drug at the same time of day. Take with or without food. Keep taking this drug as you have been told by your doctor or other health care provider, even if you feel well.

I noticed these things:

Sentences are short.

Words are (for the most part) simple and direct.

Instructions are clear and are written as imperatives.

The text anticipates possible reader questions (“… even if you feel well”).

[more]

Science supports editing guidelines, yay

Mon, 16 Jul 2018 22:00:54 GMT

There are a variety of editorial truisms: long sentences are hard to read; lists should be parallel; consistency is good. This wisdom is taught, and it's reinforced by personal experience; editors are themselves readers, after all, and they monitor their own reactions when reading.

However, there isn't always hard, empirical data that editors can point to to support what experience and insight tells them is true. But sometimes there is, and just this week I ran across something that underscores the editorial push toward consistency, and I was pretty excited about it.

I'm in a linguistics class right now, and one of our lectures was by the linguist Gareth Carrol, who uses eye-tracking studies to understand how people read. He started his lecture by noting that people do not read smoothly across the page, line by line. They stop on words (fixations); they jump (saccades); they back up (regressions). By studying what's happening with these movements, linguists can determine where people are having trouble with a text, and importantly, where they're not.

Heat map from eye-tracking study (source).

In our lecture, he discussed binomials, which are pairs of words linked by and: fish and chips, bread and butter, salt and pepper. An interesting thing about binomials is that they have a conventional order: people say I'm sick and tired of it; they don't say I'm tired and sick of it.

[more]

Only mostly true/lies to children

Sun, 08 Jul 2018 23:33:19 GMT

The other day I was taking an introductory training class for some technology at work. There was a slide that outlined the technology, and one of the bullet points had an asterisk next to it. At the bottom of the page was this footnote:

Most strong statements like this are only mostly true. Don’t worry about it.

I had to stop for a while to ponder the pedagogical implications of this footnote.

There's an inherent problem in trying to describe something complicated to a newbie: how do you start? If someone knows absolutely nothing about, say, playing bridge, or verbs in Spanish, or physics, or grammar, you have to give them a large-picture, broad-stroke overview of this thing they're about to dive into.

This is hard. One reason is that people who are familiar with some domain frequently have difficulty coming up with sufficiently high-level overviews that make sense to a beginner. I've had a couple of people attempt to explain the game of bridge to me, but they could not come up with a simple, comprehensible explanation of the bidding process.[1]

A closely related reason is that experts often cannot let go of details. For example, in your first week of Spanish class, the teacher tells you that the verb hablar means "to speak," and that to say "I speak" you cut off -ar and add -o: hablo. And that this is the pattern for any verb that ends in -ar. So to say "I take," you use the verb tomar and turn it into tomo.

Easy! Powerful! Also, of course, only mostly true: there are irregular verbs and reflexive verbs and other fun. But throwing those additional details at you in the first week of Spanish 101 is counterproductive. There will be time to sort out the exceptions later, [more]

More dubious guidance

Tue, 22 May 2018 09:37:21 GMT

I know how this happens, I do. A tech writer is given a task to "document the product," and it turns out there isn't much to say. But telling the bosses that nope, it's ok, we don't actually need to say anything about this might be perceived as, dunno, not being cooperative. Maybe even suggesting that the writer's job isn't that important.

Anyway, today we have a couple of examples of what might result if the writer (and common sense) does not prevail. First up, we have these, um, helpful instructions that came with a compass that I own:

There must be a universe in which people buy compasses who don't already know what N, E, S, and W mean. I don't believe we live in that universe.

But even that is reasonable compared to the following, which Twitter user Alex Warren posted today:

Better keep this for future reference in case I forget what each button does pic.twitter.com/UO795hO3Xn
— Alex Warren (@alexwarren) May 22, 2018

More dubious guidance: 1, 2, 3, 4, 5 [more]

Signposting in documentation

Mon, 15 Jan 2018 21:46:18 GMT
Suppose you're on vacation and you're driving to a place named Lisbon Falls. You see this sign, so you turn right.

[Source]

After you turn, you drive for a long time, but you don't see Lisbon Falls, and you start to doubt that you're on the right road. How helpful would it be to see a sign that said "Lisbon Falls—keep going "?

Obviously, we need signposts to tell us where to turn. But sometimes we need signposts to reassure us that we're going the right way. Since I work in documentation, I'm going to talk about this applies when you're writing instructions.

The first and least controversial example is to show the results of the user's action, like this:

This type of signpost reassures the reader that they've run the command correctly, or made the right gestures in the page, or whatever.

A second type of signpost is one that makes sure the reader is properly oriented at the beginning of a procedure. This comes up a lot in the complex tutorials I work with, which might have many separate procedures. What I tell my writers is that at the beginning of each procedure, they should make sure that the user is clear about where they are. Here's an example:

[more]

Using styles to set spell-check options in Word

Wed, 10 Jan 2018 08:28:46 GMT
There are many reasons to use styles in Word, as I've noted before. One feature I find handy is using styles that have different spell-check options for different types of text. I'll explain a couple of examples: one where I set a non-default spell-check option (Spanish), and another where I disable spell check for code snippets.

Note: If you'd rather see this on video, see the links below.
Spell check for non-default languages
Suppose you're writing a document that has quotations in different languages. If you run spell check over the document, it'll barf when it gets to your citations in Spanish or French or Latin or whatever.[1]

The hard way to solve this problem is to select the text of each citation, one by one, and then to set the proofing language (Review tab > Language > Set Proofing Language).

The easier way to do it is to define a style and set the language for that style. Then you can just apply the style to your citations.

Suppose I'm writing about One Hundred Years of Solitude by Gabriel Garcia-Marquez:

I run spell check, and uh-oh: if it's going to stop on every word of Spanish, it's going to be a long night proofing this doc:

Instead, I'll create a style just for my quotations in Spanish. In this case, I'll create a paragraph style, although I can set language options for character styles also, which is useful for cites in running text.

Here's the [more]

MS Word: avoiding taboo words and other tricky vocab

Wed, 05 Jul 2017 15:02:05 GMT
As most people discover, there's a class of writing error that spell check just can't help you with. Consider these examples:
We recommend that the company shit its resources for better output.
The event is open to the pubic.
Run these through spell check, and all is well. Only, of course, it's not.

As I recently learned, Word has a feature that can help find errors like this: an exclusion list. An exclusion list has words that are spelled perfectly fine, but that should be excluded from your documents.

The steps for creating an exclusion list are described in a great blog post by Sam Hartburn. The basic idea is that you add words, one per line, to .lex files in a specific folder on your computer. Here's the Windows location--see notes later for Mac instructions:

You can use any text editor to edit the file, including Notepad.

Note that there are different .lex files for different languages, and in fact for different flavors of each language—e.g. English US and English GB. (It's not inconceivable that there's a way to set up a global .lex file, but I don't know. Leave a comment if you know about that.)

Once you've got your exclusion list(s) updated, close and then reopen Word. Then when you run the spell checker, Word will flag words that are part of your exclusion list:

The examples I've shown here pertain to, you know, taboo vocabulary. Another excellent use for this feature is to flag words that you often mistype but are technically spelled correctly, such as [more]

Congratulations on your success

Thu, 15 Jun 2017 16:14:36 GMT
On Facebook today, one of the editors I know, Amy J. Schneider, posted about a habit that some writers have, namely adding a kind of reflexive "successfully" to their sentences. Here's an example, which I'm sure we've all seen variations of:

You haven't just logged off. You successfully logged off. (Thankfully, you didn't unsuccessfully log off.)

I see this all the time, and it bugs me pretty much every time. Just for yucks, I did a search for "successfully" in the documentation set I’m currently working on. I found 1473 instances; here are just a few:
Snapshot created successfully.
Successfully logged into database.
After you have successfully created the file, …
Click the Check button to verity that the service can successfully connect to your job.
To confirm that the volume was successfully taken offline, …
After the device is successfully updated, it restarts.
Make sure the test has successfully passed before you proceed.
… and on and on and on.

I ask you: is the word successfully really necessary in any of these instances? I posit that it is not. Moreover, and since I apparently am dispositionally incapable of not doing this, I ask myself "Wait, is there an unsuccessful way for this to happen?"

I reckon I could do a global search-and-~~destroy~~ [more]

Bang!

Tue, 13 Jun 2017 12:23:17 GMT
The linguist Geoff Nunberg has an essay on NPR today in which he tells of his rediscovery of the joys of using exclamation points. As he notes …
Yet writers and editors only pride themselves on expunging the marks, never on sticking them in. When it comes to exclamation points, the only virtue we recognize is self-restraint
This is true. In my work (software documentation), we maintain a tone that is, while not entirely academic, pretty neutral. Just the facts. And facts rarely require exclamation marks.

A story I've told many times: Years (decades) ago when I was learning the craft, I drafted something in which I'd included an exclamation point. My then-manager circled it and added this note: "Nix. Too exciting." I've added very few exclamation marks since then.

Technical docs have been on a path toward more friendliness, it's true. And these days especially, docs might initially be created by people who do not spend their days in the tech-writing trenches. The result is that some of these drafts can have a distinctly marketing feel to them, which of course includes exclamation points. Which I always take out.

And more than one exclamation point? Good lord. From the editor Andy Hollandbeck I learned the word bangorrhea, which is the use of excessive!!! exclamation points. The developer Rory Blyth once summed up this editorial attitude: "The use of more than one exclamation point side-by-side, in any context (except comics), is a sign of mental insanity, a marketing degree from the University of Phoenix Online, or both."

[more]

Paste unformatted text in Word

Wed, 19 Apr 2017 14:35:11 GMT
Another quick post about Word, primarily for my own benefit (when I forget this later).

Word has several options for how you can paste text:

They are (in order):
Keep Source Formatting. This option keeps the original formatting (both character and paragraph formatting), but converts it to direct formatting.

Merge Formatting. This option copies basic character formatting (bold, italics, underline) as direct formatting, but does not copy any paragraph formatting.

Use Destination Styles. This option copies the text and applies styles that are in the target document. (This option appears only if there matching styles in the target doc.)

Keep Text Only. This option copies the text as plain text, with no formatting.
I need the last one (paste plain text) more often than any of the others, so I want it on a keyboard shortcut. You can do this by recording a macro of yourself using the Keep Text Only option. But I realized there's an even easier way—just assign a keyboard shortcut to the built-in PasteTextOnly command.

I keep forgetting that most anything Word can do has a command. If a gesture requires just one command, you can assign a keyboard shortcut directly to it. Maybe writing this out will help me remember.

Update I added a video!

Word macros for displaying styles in the Styles pane

Mon, 14 Mar 2016 00:01:22 GMT
This is another in a series of blog posts about how I configure Microsoft Word, which I add here primarily for my own reference.

I often use the Style pane, and within that pane, I often want to change the styles that are displayed. Sometimes I want to see all the styles; sometimes just the styles that are defined in the current document; sometimes just the styles currently in use.

You can change this display by using a dialog box. In the Styles pane, click the Options link, and then use the dropdown lists to select which styles to display and how they're ordered, like this:

But that can get to be an annoying number of clicks if you're switching between these display options frequently. So, macros to the rescue. I recorded myself making one of these changes, then created a couple of variations to give me the different displays I want. Here are the macros I currently use, where the sub name is (I hope) self-explanatory:
Sub SetStylesPaneToAllAlphabetical()
ActiveDocument.FormattingShowFilter = wdShowFilterStylesAll
ActiveDocument.StyleSortMethod = wdStyleSortByName
End Sub

Sub SetStylesPaneToInCurrentDocument()
ActiveDocument.FormattingShowFilter = wdShowFilterStylesAvailable
ActiveDocument.StyleSortMethod = wdStyleSortByName
End Sub

Sub SetStylesPaneToInUse()
ActiveDocument.FormattingShowFilter = wdShowFilterStylesInUse
ActiveDocument.StyleSortMethod = wdStyleSortByName
End Sub
To complete the picture, I map the macros to these keyboard shortcuts:

ctrl+shift+p,a — SetStylesPaneToAllAlphabetical
ctrl+shift+p,c – SetStylesPaneToInCurrentDocument
[more]

AutoFormat in Word

Tue, 08 Mar 2016 00:23:08 GMT
I have used Microsoft Word for years—decades—but hardly a week goes by when I don't learn something new. (Including things that are probably pretty well known to others, oh well.) Anyway, TIL about how to use the batch version of auto-formatting in Word. Since I think a lot of people already know this, I'm adding the information here primarily for later reference for myself.

Word has settings to perform "auto-formatting as you type." These include things like converting quotation marks into so-called smart quotes (i.e., typographical quotation marks), converting double hyphens (--) into em-dashes (—), converting typed fractions (1/2) into typographic fractions (½), etc. You set these options in the AutoCorrect dialog box: File > Options > Proofing, AutoCorrect Options button, AutoFormat As You Type tab.

It turns out that Word can also apply these auto-formatting instructions after the fact. In the same AutoCorrect dialog box, there's a tab named just AutoFormat:

This has most of the same options as with auto-format-as-you-type. Here's the neat part: you can get Word to apply these formatting options by pressing alt+ctrl+k. There's no UI gesture, but you can use the feature for customizing the ribbon to add the relevant command to the ribbon or Quick Access Toolbar.

A use case where I can see this working pretty well is if you paste text in from a text editor. (I do this all the time.)

Credit where it's due: I learned about this from the article [more]

More on ambigious "should"

Tue, 12 Jan 2016 09:04:43 GMT
I was reading a thread on a computer forum, and someone asked this question:
Quote:
Your password should contain at least 6 characters

If you're going to require it; don't say "should", say "must".
This set off an interesting discussion on the semantics of should in this context. I've written about this before, so I was interested to hear how people interpreted the example.

Here is a sampling of the more serious posts on the thread:

From the requirements document: "The password entered by the user should be rejected if it does not contain at least six characters." If I received that requirement from my boss, I would make darn sure that the password is rejected. I don't think I would randomly reject some and not others.

The software is being polite; it's anticipating users who do not like being told what to do.

If it says "should" then it is not optional, like in "could". You should be "this tall" to ride this ride.

A number of people pulled out dictionary definitions (Wikitionary, heh). And one person cited RFC 2119 ("Key words for use in RFCs to Indicate Requirement Levels"), which states:

MUST This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.

[more]

We'd better document that

Mon, 03 Aug 2015 21:54:24 GMT
From my daughter, another example of poor design patched by documentation.

Who imagined that a) having an unlabeled numeric scale was a good idea, and b) you move the knob to the right for "colder"?

Let's at least fix the first problem, shall we? Like this:

We can't use documentation to fix the problem of having to dial "more cold." But at least we don't to print a frickin' manual right on the freezer.

Update 4 Aug 2015 In response to Hal's comment, here's an improved design that even has redundancy for those who aren't sensitive to color differences.