Category Archives: If I Had My Document Way

If I Had My Document Way… Official Templates

If I Had My Document Way

…official templates would not be created by the unqualified.

That sounds snobby, but if you end up using a template that looks all right, but has all the problems I’ve talked about in these posts, then it becomes a problem for everyone. Don’t delegate it to anyone who has the time.

Give it to someone who has the knowledge and the experience to create something that is correctly set up and will hopefully prevent many of the issues we see.

 

If I Had My Document Way… Numbering Would Include All Levels

If I Had My Document Way

…heading numbering would by default include all previous levels of numbering.

What does that mean? Here’s an example of heading numbering (this is BAD, and is used by US government documents like the CFR):

1. This is heading 1

a. This is heading 2

b. Heading 2 again

i. This is heading 3

A. This is heading 4

2. Heading 1 again

a. Heading 2 yet again

Body text example.

i. Heading 3 again

ii. Heading 3 yet again

The problem here is figuring out the absolute reference for the ‘Body text example’. It’s under a), OK. But what is that under? In this small example you can easily see that it’s under 2. So the example is 2a).

But if section 2 started several pages before, you would have to flip back and find what the previous level was. You might miss it, and get the wrong reference. It’s a pain.

This is a better solution – include the previous levels in each heading number:

1. This is heading 1

1.a. This is heading 2

1.b. Heading 2 again

1.b.i. This is heading 3

1.b.i.A. This is heading 4

2. Heading 1 again

2.a. Heading 2 yet again

Body text example.

2.a.i. Heading 3 again

2.a.ii. Heading 3 yet again

Much clearer. You can see straightaway that the body text is in section 2.a, even if section 2 started pages before. You don’t even need the indentation.

However, I don’t like the combination of numbers, letters and Roman numerals. Once you get to four levels, you have to start using upper and lower case to differentiate, and below that you have to use italics and other formatting. Nasty, unclear and confusing.

I much prefer to just stick with numbers, and to include all previous levels in the heading number, as follows:

1. This is heading 1

1.1. This is heading 2

1.2. Heading 2 again

1.2.1. This is heading 3

1.2.1.1. This is heading 4

2. Heading 1 again

2.1. Heading 2 yet again

Body text example.

2.1.1. Heading 3 again

2.1.2. Heading 3 yet again

Much nicer.

Now, there is an argument to be made for putting numbers in front of every paragraph, so that you can immediately refer to a clause in a document. Legal documents do this of course, but they also use weird-shaped paper, so we can safely ignore that industry. The numbers would increase greatly, and you’d need to make sure the Styles and Table of Contents played nicely together, but it would be very useful, especially in my field of Requirements Management, where each paragraph is a clause to be tracked and addressed.

If I Had My Document Way… Version Control

If I Had My Document Way

…all documents would be in a version controlled central location.

This is not about formatting, it’s about keeping track of all the versions of a document, especially one that is being edited by multiple people. Too much of the time, we rely on email and MS Word’s powerful-but-limited Track Changes feature to enable collaboration. Documents get emailed around, someone edits it, the changes are marked, it’s emailed onward, more copies are made, more emails are sent, who’s got the latest? I sent it yesterday, no that was the old one, well it’s got my edits in it, those were addressed in the new version, I haven’t seen that, I’ll email it to you, no just send me the link to the latest version on the server.

“No, we haven’t finished the document yet, so it’s not in version control. Once it’s approved, then we’ll upload it.”

True story.

The point is that these version control systems and products exist, Electronic Document Management Systems, and they manage this stuff very well. It’s what they’re designed to do. They manage the “churn” of many edits being made to a document by multiple people. They control access so that changes don’t conflict.

But they can be tricky to apply, or set up, and if there’s one thing that projects like to save money on, it’s engineering administration tools like EDMS’s.

“They’re expensive, people don’t know how to use them, they don’t want to learn, they say they’re engineers, not editors or software developers. We can just do it with email and Track Changes like always.”

…and deal with the consequences. Again and again. That’s how you end up with the story described above. Despite the tool being designed to deal with the “churn”, you deliberately avoid using it until the benefit has passed. You’ve spent the money on the tool, but because it’s not set up correctly, or people aren’t made to use it, it gets ignored, and the organization is loathe to make the effort next time.

Kind of how the Tories treat the NHS: Little or no investment in the tool, poor results from the tool, blame the tool. We see this time and time again.

Take some time, a little bit of money and little bit of effort, set up the EDMS properly, train people to use it, enforce it, and it will solve so many problems. Unfortunately, the value and benefit may not appear until later in the project, or perhaps in a later project.

If I Had My Document Way… Formatting Marks

If I Had My Document Way

…formatting marks would show what formatting would be applied to the text. This is a little more technical, but I think it would solve a lot of problems.

I don’t want to be one of these people who claims that WordPerfect 5 (or is it WordStar I’m thinking of?) was the best ever, because it wasn’t (for many reasons, oof), but it did have one feature that could be useful now, and that was the separation between the Print Preview view and the editing view. When editing, you saw a screen of text, which didn’t look like how it would look when printed. If you wanted to see that, you would switch to Print Preview mode. You couldn’t edit the document in this WYSIWYG mode. When you switched back to edit mode, the text was marked up with little symbols and codes to show how the text was formatted. It was right there, you could clearly see what was going on.

I can see why WYSIWYG is attractive to people; you can just see how things will look. But it also means that the structure of the formatting and data required to make it look right is hidden from the user. The user then forgets about it, and that’s when problems start.

I’m not advocating a return to the 80s (not in this particular regard anyway) but to be able to directly see why something looks the way it does, or is positioned the way it is, would be very helpful.

(It’s a lot like HTML in that regard, with CSS as the Styles… Hmm…)

If I Had My Document Way… Styles Would Be Taught First

If I Had My Document Way

…Styles would be taught first, instead of being reserved for the advanced class.

I’ve found that basic MS Word training teaches users to apply formatting directly. But I think they would be better served by teaching them Styles in the first lesson (after the absolute basics like opening, saving, and the like). They should be taught:

  • How to apply Styles so your text is consistently formatted.
  • How to edit Styles so you can change all instances of that text on one go so it remains consistent.
  • Advanced: How to sort heading numbering out.

You want Body Text? Select, apply Style. You want this to be a Heading 2? Boom. Not “select, choose big font, choose justification, whatever”. Styles. I know I go on about Styles all the time. I like Styles. The implementation in MS Word is clunky, but it’s the best we’ve* got.

* by “we” I mean “people forced to use MS Word in a corporate setting”

 

If I Had My Document Way… Heading Numbering by Default

If I Had My Document Way

…Word’s default Headings would have a proper numbering setup. By default, the headings in Word don’t have numbers. The standard template has a blue Heading 1, then some other font for Heading 2, etc. No numbering. This means the first thing you have to do in an empty document is set your numbering up, and that is complicated. This means you’re at the mercy of the defaults, or you use some corporate template created by someone who doesn’t know what they’re doing and how important it is, or you copy stuff in from another document, carrying all the contamination of dodgy Styles with it.

What Word should do is have a basic simple numbered heading scheme set up as an option, or maybe by default. Then everyone would know straightaway what was possible, what was desirable, and what was best practice.

What would that basic default be? Stay tuned for a suggestion.

If I Had My Document Way… Paste Formatting

If I Had My Document Way

…paste formatting would be removed. That trick where you can select some text, click the ‘Paste Formatting’ paintbrush button, then paint that formatting on some other text is the cause of many problems I’ve seen in documents. Applying some random formatting to a chunk of text, instead of using the proper Style for that text, means that you end up with text with formatting that is in conflict with the Style it is in.

For example, you might have a bunch of text that is currently Body Text, but you want it to look like a Heading 1. What you should do is click in it and select the Heading 1 style. But because people see the convenient ‘Paste Formatting’ button, they paint the text to look like a Heading, instead of actually changing it to be a Heading. The next time they update the Table Of Contents, that text doesn’t show up because it’s not a real Heading, they get confused, say, “Word is stupid, I’m doing this stuff manually”, and then they’re lost forever.

Don’t use Paste Formatting.

 

 

If I Had My Document Way… In-line Pictures

If I Had My Document Way

…all images, diagrams, charts etc would be in-line with text, not floating in relation to the page. That little anchor symbol drives me crazy. The image is related to the text, right? Then stick it in the text. Otherwise (from what I’ve seen), the text moves when it’s edited, and the image it’s related to doesn’t move with it, and you end up with weird gaps and floating things that don’t fit anywhere.

Stick it in-line the text, don’t wrap the text around it, and put a caption after it.

 

If I Had My Document Way… Paste Unformatted

If I Had My Document Way

…the default paste setting in MS Word would be “Keep Text Only”. I think this is one of the most important issues. Currently, when someone pastes text from one document into another, the default behavior is to copy the text and the formatting, including whatever styles are attaches to that text. This can cause all sorts of trouble, especially if the text has some numbering, or is in another language. You end up with a document containing a mish-mash of text styles, languages, conflicting formatting and all sorts of mess.

If the only thing that was pasted was the raw text, and it took on whatever formatting it was pasted into, then your document remains clean and pure, untainted by whatever monstrosity you’re plagiarizing from.

Luckily this setting can be changed, but it requires digging around in the options and training people (like all of these tips).

Do this is in MS Word 2007: Office Button > Word Options > Advanced > Cut, copy and paste > change 4 pasting drop-downs to “Keep Text Only”

You’ll thank me.

If I Had My Document Way… Section Breaks

If I Had My Document Way

…section breaks would not exist unless absolutely necessary. The front page would be the first page of Section, and it could be different from the second page onwards. The footers would be consistent, the page numbering would be consistent, weird formatting errors would not arise as a result of scattered unnecessary section breaks everywhere. The only time they are required is when you need to switch from portrait to landscape or back. You wouldn’t see document with a “Section Break – New Page” at the end of the title block, after the contents page, after the introduction, after each chapter.