Sharp Words

7 out of 10

The kind people in the marketing department at Hodder & Stoughton sent me an advance reading copy of this, so naturally, I’m reviewing it, even though it’s not my usual sort of reading material.

Even without it being the sort of thing I’d usually read, I did enjoy this novel a lot. It’s a sweet little romance story with fantasy elements that wouldn’t be too strong for someone who doesn’t normally read fantasy (it’s the ‘romance’ aspect that isn’t something I normally read!) with appealing characters and a happy fairytale-like plot.

Claire Waverley lives in Bascom, North Carolina, in the house where generations of Waverleys have lived. She’s a professional caterer, using the plants that grow in her garden to produce some interesting dishes which do more than just please the palate. Although she has few friends and an outwardly boring life, she’s content enough until her younger sister Sydney comes home with daughter Bay in tow, right after the very interesting man next door has made his interest in Claire very clear.

The story covers how Claire and Sydney deal with the changes in their lives over a few weeks of summer, and features an engaging cast of supporting characters.

• Continue reading or Leave a comment... (4)

As mentioned in my post about the documentation process, there are two types of review which your technical documents should ideally be put through.

Technical Reviews
Technical reviews should be done by a subject matter expert (SME) – in other words, someone who knows all about the technical thing you’ve written about. In practice, this is usually the engineer who built the item or the developer who wrote the software, or maybe a tester or member of the customer-facing technical support staff. If, as happens a lot with my documents, a new section of document was written in response to a request by someone within the company, it’s a good idea to get them to review it too.

You might have more than one SME involved in reviewing the document.  If appropriate, flag the review copy for each reviewer so that they don’t waste time reviewing something they don’t know much about – they’ll thank you for this, believe me!

Generally, any review comments about the technical contents of the document must be applied – after all, your reviewer is the expert. Of course, if you disagree with changes they’ve suggested, or you’ve had conflicting suggestions from different reviewers, it’s always best to get clarification.  Dealing with review comments is something I’m going to cover in my next post in this series.

Peer Reviews
A peer review is generally done by another technical writer. If you’re working by yourself (perhaps for a small company, or on contract), then you need to find someone with a good grasp of grammar, who also knows about how to structure information and how to use a style guide (assuming you have one).

Your peer reviewer should be checking for:

• general readability – in other words, does the order and wording of the information given in the document make sense to a reader and user?
• writing issues – grammar and spelling problems
• adherence to any style guides – it helps if they’re familiar with the usual format and formatting of the documents you produce

Changes suggested by a peer reviewer are frequently subject to debate – for example, you might think one way of wording something is more appropriate than the way they might prefer. As mentioned previously, dealing with review comments is something I’ll tackle in my next post in this series.

Very often, your technical reviewer will check for these types of things too. It’s a good idea to tell the SMEs beforehand whether you want them to look for such issues or not. I’ve had plenty of review comments back from SMEs where they’ve spent a couple of hours correcting the wording in a document (even though that wording was dictated by the style guide) but without spending any time looking at the technical content they were supposed to check!  Also make sure that your reviewer knows what they’re supposed to be looking for – and if they only need to check a small section of the document, either give them just that part or flag it up for them.

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts

• Leave a comment... (1)

Here are some blog posts I’ve found interesting of late (and I freely admit that this post is partly filler):

• “An Introduction to the Vocabulary of Poetry” – Writing Forward – a run-through of ways of using words in poetry, such as alliteration and assonance
• “More on Found Poetry” – The Writing Nag – an interesting explanation of how to take phrases from pretty much anything and assemble them into poems; I keep meaning to try this for at least one of my NaPoWriMo poems…
• “You Write Badly: Six Seriously Annoying Writing Mistakes To Avoid” – Blog Badly - six style-related things to avoid when writing blog posts
• and mostly for fun: “Can You Pass This Test?” – Dot Com Mogul – does your left brain or your right brain rule? Can you swap between them? (I could, with effort!)

• Leave a comment... (6)

When creating technical documents of any kind, it’s sensible to have a process to follow. In this article, I’m going to list the process I’d use to write a brand new document; it can be easily adapted for updates to existing documents.
Disclaimer: this process is what works for me and for other technical writers of my acquaintance; it’s not the only way of creating tech documents!

Step 1 – Gathering Information
There are a variety of tasks involved at this point, but the important ones are:

1. Defining the subject matter and audience of the document – i.e. what is the document about and who will use it?
2. Defining the document output – this determines not just the tools you use to create the document but can also affect its structure.
3. Getting an overview of the material to go into the document – if the developers or engineers have written requirements or specification documents, these can be very useful.

Step 2 – Outlining and Estimating
These two tasks can be done together, as the outline of the document dictates how long it will take to write.

The outline of a document is basically its table of contents (TOC). Drawing up a draft TOC may require a more in-depth look at the subject matter, for example, being walked through a piece of software by its developer.

Once you have a draft TOC, you can estimate how long it will take you to fill in the content. There are various methods of working out documentation estimates, but I’m not going to go into them in this article – there’s certainly no definitive method, and it’s often just a case of what works best for a particular writer or team.

When estimating, don’t forget to include time already spent on the TOC, plus time spent on creating the document itself, such as plugging chapter headings into a template, and indexing. It’s also essential to include time for reviews and review updates.

Step 3 – Writing
This is the core of a technical writer’s job, isn’t it? Well, perhaps, but I know a lot of us spend most of our time doing anything but actually writing document content! The job of writing (in this process) also includes the time spent setting up the document, creating graphics, and indexing.

Step 4 – Reviewing
It’s vital that your documents are reviewed by subject matter experts (SMEs) and by other technical writers (where possible). The SME is generally someone who worked on the document’s subject (e.g. the developer or engineer), and they review for technical accuracy. The technical writer performs a peer review for grammar, spelling and writing style.

You then need to apply any appropriate updates to the document, and send it through further review cycles until everyone’s happy. Usually, there’s some sort of sign-off or authorisation for the finished version.

I’ll be covering the art of reviewing and dealing with reviews in later articles.

Step 5 – Publishing
The final part, determined by the output required: for example, online help, printed guide, PDF or web site, or all of these!

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts

• Leave a comment... (3)

Dammit, I got tagged for a meme by Haley of The Beacon. She originally suggested that the eight random things should be writing-related – she’s since recanted, but since this is my reading & writing blog, I’m going to stick with the theme anyway.

The Rules:

1. Each player starts with 8 random facts/habits about themselves.
2. People who are tagged, write a blog post about their own 8 random things, and post these rules.
3. At the end of your post you need to tag 8 people and include their names.
4. Don’t forget to leave them a comment and tell them they’ve been tagged, and to read your blog.

So. Let’s try this.

1. Somewhere, I have a copy of the first full book I ever wrote, The Flying Swallow Club, which I bound into a ‘proper’ little book with illustrations traced from Ladybird books about birds. I was about 10 and I remember asking a boy in my class (who I really liked) how fast he thought swallows could fly. This was fortunately a long time before I became aware of the differences between African and European swallows.

2. By the time I was about 11, I owned around 350 books, all catalogued in a card index. Well over a hundred of those were by Enid Blyton. I even owned a date stamp so I could run my own library and lend them out to friends – there are still a couple of books I regret never getting back (Prince Caspian was one of them, though I bought a replacement years later).

3. Every time I see an apostrophe out of place, I have the urge to get a pen out of my bag and correct it. I don’t though, because my friends would be horribly embarrassed. But the urge is always there.

4. Since the start of 2006, I’ve been logging everything I read – which is why I started this blog, in fact. The logs used to be weekly, but they’ve become monthly this year, since I started taking my blogging more seriously. They’re probably not very interesting reads, but I find them useful to see what I’ve read; there are far too many half-remembered books in my head.

5. And most of those half-remembered books date back to when I discovered that the SF/fantasy shelves were right next to the Young Adult ones in the main library, after I graduated from the children’s library at the age of about 12 or 13 – and thus was triggered a lifelong love of those genres.

6. I used to read my mum’s library books, 10 or 20 pages at a time when I could sneak a look at them. Some of them were way too old for me, but I don’t think any serious harm was done.

7. And in other library-related trivia, I was once a member of six lending libraries simultaneously (not even counting the one that consisted of my own books, stored at my parents’): my university library; the fiction library in my university college/hall of residence; the library in my home town; the library in the city nearest my home town; the library in my university town; and the library in the town where I lived when I was at university. I could only take books out of a maximum of four of them though, as my university was a couple of hundred miles from home.

8. This one is something I’ve mentioned before on this blog, in passing: I don’t like editing my poetry. Stories and novels, yes, those have to be edited… but I like my own poems to be ephemeral, to represent a particular state of mind or being, without being changed into something else by hindsight. (Although I will correct bad spelling or typos, of course.)

I think that’ll do for now? I’m going to be lazy and not tag anyone specifically, because a lot of you have probably seen this meme before (though I’m sure it was only seven things last time I did it). But if anyone decides to have a go, leave a comment!

• Leave a comment... (9)

“If a cluttered desk is the sign of a cluttered mind, what is the significance of a clean desk?”
Laurence J. Peter
[Quote supplied by the Quotations Page]

Although this isn’t strictly a writing-related quote, it caught my eye when it appeared in my feed-reader this morning.

Personally, both my home and office desks are very cluttered. But it’s the quality of clutter that differs. In work, there’s nothing on my desk and shelf that isn’t necessary: books, magazines, papers, pens and pencils, my mug, my daily apple, a box of fruit teabags, the laptop, the desktop PC… Although come to think of it, the odds and ends (some of them very odd) tend to end up in my drawer rather than being on display.

My home desk, on the other hand, is just messy. There’s a lot of rubbish lying on it that I really should sort through and throw out (old receipts and that sort of thing); the cables are all jumbled, half the CDs are out of the rack, papers aren’t sorted properly… that sort of thing. (My drawers at home are just as bad, too.)

So, is it any wonder that I find it easier to concentrate when I’m in the office, and don’t spend so much time fumbling round for what I need?

• Leave a comment... (9)