About

I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search


(Supports AND)

Google Ads

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

Some of the best things in life aren't free.

Gretchen Rubin



Navigation





<January 2018>
SMTWTFS
31123456
78910111213
14151617181920
21222324252627
28293031123
45678910

Categories

  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  

Contact

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 1/19/2018

Totals
Posts - 2476
Comments - 2570
Hits - 2,016,100

Averages
Entries/day - 0.47
Comments/entry - 1.04
Hits/day - 379

Updated every 30 minutes. Last: 8:57 AM Pacific


  11:33 PM

I'm currently editing some documents that were created by someone outside our group -- that is, not by one of our tech writers. The docs were created in Microsoft Word, of course, which has many benefits for us, like the ability to use revision marks and comments.

I have always the same reaction when I work with docs like this, which is this: people have no clue how to use Word styles. People who are obviously bright, who have skillz with all manner of programming tools, who whip out Excel spreadsheets (our other lingua franca), even who use Word all the time for specs -- a lot of these people use Word like amateurs.

(For us writer types, there's no choice. Our authoring tools have a very closely circumscribed set of styles we use. Only. In fact, you cannot apply local styling -- even something as innocuous as bold -- to any text in any of our documents. There's a reason for this, as I'll note momentarily.)

Why get so het up about styles? They are, after all, a formatting aid, and Word has plenty of ways to format text that don't involve defining and applying styles. True, mostly. And styles might seem to be sort of inconvenient if you're not used to working with them, altho for those who know what they're doing, styles are often faster than local formatting. (I'll be happy to demonstrate, should you doubt this statement.)

Here are some reasons I can tell you off the top of my head why styles are good and why you should use them.

Cleanliness. Without styles, people will resort to some goofy ways to format text. Most people, thank god, know enough not to indent text by using some horrific combination of returns and tabs (or spaces, gad). Most, but not all; I've seen text that's been "centered" with tabs. But many (many, many) people, when they want a space between paragraphs, the only thing they know to do is put a blank paragraph there. Is the spacing not correct? I know! I'll make it a 16-point blank paragraph mark! Or I'll use a couple of soft returns, coz dang, I just cannot seem to get this spacing right.

This stuff is just junk, detritus in the document that clutters it up and that if it ever comes to me, I have to fix up.

Global changes. Surely this alone is an argument for styles. What happens if you decide that all that text that you formatted as Courier New 10 point would really look better as Lucida Sans 9 point? If you manually formatted every Courier New character by hand, that's going to be a lot of reformatting, amigo.[1] What if you want to change what bullet character you're using? The base font for the document, even?

Formatting independence. Here's something I see all the time -- someone has written a document that has text and code samples and HTML bits and a bunch of stuff. It will all look different, because the author will have formatted the text as, dunno, Calibri, and the code as Courier New and the HTML as Courier New, but with all the keywords nicely colored. Something like that. But every single last line of text will have as its style ... Normal, which is the default style in Word. Now, suppose you want to change paragraph spacing, give those text paragraphs a little room to breathe. In the definition for Normal, you add 6 points before and after each paragraph, and ... whoops! All the code is now double spaced, because each line of code is its own paragraph. Dang. Ok, well, guess I better just add blank paragraphs between each block of text ...

By using styles -- in this case, paragraph styles -- you can control the formatting of each paragraph type independently. For each type of paragraph you have -- text, bulleted list, numbered list, indented paragraph, code paragraph, indented code, notes, etc., etc. -- define a different style whose formatting you can play with all you want and not affect any other text in the document.

Semantic tagging. Your document has some C# code in it, so you style is as Courier New. And there's a snippet of HTML, so you style that Courier New as well. (You're sort of in a rut on the monospace thing, but we'll leave that to Jeff Atwood.) You reference a variable in text; Courier New. When you discuss the new keyword, how to format it? Courier New. User input? How about Courier New?

Now some scenarios. First, the aforementioned change of heart. After you look at this gray expanse of blocky lettering, you decide that code could be Lucida Sans, keywords could be bold, user input could be italic. Too bad for you: you now have to find each instance, decide what it is, and change it accordingly.

Or, you're now going to repurpose the doc from a Word document into an HTML document. Or better yet, an XML document. What's going to happen with all your blobs of Courier New text? Well, they'll be blobs of Courier New text and that's that. Whatever intent you might have had about the semantics of individual text elements is lost and it all goes into the same bucket.

What you should do, of course, is to create a separate character style for each of these types of text and apply it individually: language keyword, user input, HTML text, code text, etc.

I noted earlier that our authoring environment is insistent that we use a very strict list of styles. That's because our Word files are transformed into XML which goes through various further transformations before it ends up on (for example) MSDN as HTML. When I get a document from some outsider, and if that document is intended for MSDN, guess who gets to go through and turn all the author's random styling choices into the prescribed list of (semantic) styles? That's right ... me.

Style sheets. One of the real benefits of styles, of course, is that you can persist them into Word templates (aka .dot files). You can define default styles that are available when you create a new document. If you need a style that's not in the current template, you can define and add it, or you can merge styles from other documents or templates.

Word has powerful facilities for managing styles. Word makes it easy to define a paragraph and then derive a style from it; to create new styles from scratch; to modify existing styles; and to easily apply styles, yea, verily, with the keyboard. (Stop by, I'll show you how.)

Where have you heard this, all of it, before? CSS styles, of course. CSS people will tell you all the same things I've said here (plus more), and for many of the same reasons. Namely, if you don't use styles, you create junky documents that are a mess to change.

It's a matter of knowing how to get the best from your tools. If you're writing to grandma, fine, center that paragraph with tabs, I don't care. But if you're creating professional documents in Word -- especially documents that will go through other people's hands and that will go through a professional publishing process -- then use styles; it's that simple. And if you don't know what styles to use, don't just make stuff up. Go talk to your editor. Trust me, they'll know all about it.


[1] If you're clever and lucky, you might be able to use search-and-replace for this; it can search and replace formatting. Still a pain, though.

[categories]   ,

[4] |