Tuesday, 29 March 2011
01:04 AM
We've always used Microsoft Word as our authoring tool. One of the really compelling reasons is that it has sophisticated ways to manage reviews. That is, it supports revision marks and it allows comments, which we use heavily[1]:
I'm not going to say much about revision marks in Word, except that I'll note a few somewhat irrelevant (w/r/t this post) tips that there are two keyboard shortcuts that are very handy when you work with rev marks:- Ctrl+Shift+E = Toggle revision marking on/off. The status is, or can be, shown in the status bar:
- Alt,V,A = Toggles between messy view and "Final" view, which shows you what it looks like if you accept all revision marks (and, of course, hides the marks and comments).
I also map three Word commands to keystrokes in order to facilitate my work with rev marks:- Alt+Ctrl+F = NextChangeOrComment
- Alt+Ctrl+A = AcceptChangesSelected
- Alt+Ctrl+R = RejectChangesSelected
As I say, not really on topic here. But perhaps useful.
Editing HTML
One of the challenges we've been facing recently is that a lot of the documents we're creating aren't Word docs (.doc or .docx files), but HTML files. Word is not a great editor for HTML files. Or to put it more precisely, it's not a good choice when it's important to produce very specific (and very clean) HTML. (Even for "filtered" HTML, I'm sad to say.)
From an editing workflow POV, HTML does not support the kind of revision marks and comments that we're so used to in Word. In Word documents, revision marks and comments are metadata; they are not part of the text of the file. HTML does support <del> and <ins> elements, but these are just tags. There are no tags that you can use to surround text in the document to say "this is deleted" that are not also part of the document. And there are no elements that you can use to mark comments to the writer that are not also visible to any reader.
What to do? Well, since we can't change HTML, we've been obliged to change our workflow. What we're experimenting with (I emphasize that this is not formalized) is to indeed use <del> and <ins> elements. To make these elements more useful, we've taken to adding a style block to the top of HTML files that looks like this:
ins {
background-color:yellow;
color:green;
}
del {
background-color:cyan;
color:red;
text-decoration:line-through;
font-weight:bold;
}
These style definitions cause text in <del> and <ins> elements to show up like this:
The actual characters are still in the file, of course, but are substantially easier to see when the page is displayed. And because the text is tagged, it's easier to deal with later. To make this approach feasible, we do the following:- Use Microsoft Expression Web to edit the HTML files. This isn't a requirement, but Expression has some features that make it easy to quickly apply an element (
<ins> or <del>, obviously) to selected text.
- Use
<ins> and <del> tags rigorously and exclusively to mark insertions and deletions.
- Religiously do a pass at the end of the cycle to find and delete
<ins> and <del> tags (including the latter's content) before we publish. (Expression has nice facilities for this, too, or we could practice our regular-expression chops if we wanted).
This is still far from perfect. Word lets you track revisions by reviewer; my edits and those of the writer are distinct. There's no such sophistication here.
What about comments? We're still sorting this out. We've experimented with using an <ins> element that either has local formatting (like italics) or a class attribute.
You can see where the problems are here. The scariest is the possibility that we might miss an <ins> or <del> element and that text gets published. It hasn't happened to us yet, but the possibility is distinct, because it's only process that prevents it.
Editing in Wikis
An even more challenging problem for editorial workflow is editing wiki content. Some of the products we work on these are documented only via wikis. (example, example). Depending on what wiki engine we're working with, we might be able to use HTML, or we might not. (Some or our wikis use a special markup language called Markdown.) In neither case is it practical to use <ins> and <del> elements as we've been doing in our own HTML files. In some cases we can save interim versions of a file as a draft, which at least makes it practical to iterate on a document before it's live. But sometimes we're obliged to work directly in live documents.
I can't say that we have a particularly good solution to this issue at the moment. To some extent, we're relying on the wiki ethos itself — in the world of wikis, there is no draft versus final version; there is no final version. Every document is endlessly editable.
What this means for us is that a writer can draft and post a wiki page. I can edit the page and make all the fixes I want. If the writer wants to see specifics of my changes, there's always history that the writer can compare to the current version. In effect, our writing-editing cycle is on public display for anyone who is watching minute changes in wiki topics, and is available in full from anyone who can see the history in a page.
This isn't a bad thing, really. But it does limit the aspect of editing in which the writer and editor converse via the text, through revision marks or comments. What I've taken to doing when I edit a wiki file is to create a new file into which I add notes, questions, and comments. When I'm done with a wiki topic, I'll save it (which makes it live) and I'll send the file with notes in it to the writer. Needless to say, this is substantially less convenient than being able to leave edits in the file itself.
I sure am curious whether other people have developed more sophisticated ways to manage an editing cycle for these types of situations – namely, pure-HTML file and wiki-based files. If you know of any, by all means, let me know.
[categories]
writing, editing
|
link
|