Over the weekend I read the book Spring Into Technical Writing for Engineers and Scientists by Barry Rosenberg. It's lead me to a couple of realizations:
The following is a quick overview of the book. The short version is that I would recommend this book to anyone in this field. If you are a tester or developer, pick up a copy.
The book is broken up into four sections:
I. PLANNING TO WRITE
II. WRITING: GENERAL PRINCIPLES
III. WRITING: SPECIFIC KINDS OF DOCUMENTS
IV. EDITING AND PRODUCING DOCUMENTS
I. PLANNING TO WRITE
Other then an interesting example of creative technical writing in the first chapter, this section didn't offer me much, but it contains necessary information for a writer. If you have read anything on writing in the past (or have been successfully published), then odds are you are already aware of audience and how to plan your writing.
II. WRITING: GENERAL PRINCIPLES
This section was excellent. Like the previous section, this one contained basics. However, unlike the previous section, these basics need to be read over and over again. They are the building blocks of good writing. It contains practical advice - like the following simple advice on using verbs:
And advice on causes of long sentences (my worst problem):
This section is required reading for me. I think I will try to re-read this section every couple of months. Each chapter in the book ends with a series of questions relating to the topics covered. At the very least I will use those questions when editing my work.
III. WRITING: SPECIFIC KINDS OF DOCUMENTS
This is the section that I think would be most useful to developers and testers. It takes a look at writing specific types of manuals:
It also has an excellent section on giving presentations. I know that a lot of people in this community present at conferences, so I would recommend that section specifically (even though it has an initial focus on PowerPoint).
IV. EDITING AND PRODUCING DOCUMENTS
This section focuses on editing and the editing process. I think I pulled more useful information on editing from section II, but there is still good information here if you have never been through the process before. The most interesting tidbit I pulled from this section was the following comparison of punctuation to music and timing:
It's an example that's both meaningful and memorable. I think I've been using dashes incorrectly for the last four years.
The writing style for the book made it enjoyable to read. Rosenberg has a sense of humor and makes a rather dry topic interesting and fun to read. The fact that I read it in one weekend is a testament to that. It typically takes me weeks to work through a book on writing.
- I don't write as well as I'd like to.
- I don't speak as well as I'd like to (I really already knew this - this book just confirmed it).
- I don't spend enough time focusing on my writing and speaking.
The following is a quick overview of the book. The short version is that I would recommend this book to anyone in this field. If you are a tester or developer, pick up a copy.
The book is broken up into four sections:
I. PLANNING TO WRITE
II. WRITING: GENERAL PRINCIPLES
III. WRITING: SPECIFIC KINDS OF DOCUMENTS
IV. EDITING AND PRODUCING DOCUMENTS
I. PLANNING TO WRITE
Other then an interesting example of creative technical writing in the first chapter, this section didn't offer me much, but it contains necessary information for a writer. If you have read anything on writing in the past (or have been successfully published), then odds are you are already aware of audience and how to plan your writing.
II. WRITING: GENERAL PRINCIPLES
This section was excellent. Like the previous section, this one contained basics. However, unlike the previous section, these basics need to be read over and over again. They are the building blocks of good writing. It contains practical advice - like the following simple advice on using verbs:
- Choose strong verbs
- Avoid overusing to be
- Vary your verbs
- Keep verbs in the same tense
And advice on causes of long sentences (my worst problem):
- Jamming two or three ideas into a single sentence
- Using passive voice
- Being repetitious
- Using words or phrases that don't pull their weight
- Embedding lists that should be broken into bulleted or numbered lists
This section is required reading for me. I think I will try to re-read this section every couple of months. Each chapter in the book ends with a series of questions relating to the topics covered. At the very least I will use those questions when editing my work.
III. WRITING: SPECIFIC KINDS OF DOCUMENTS
This is the section that I think would be most useful to developers and testers. It takes a look at writing specific types of manuals:
- cookbooks
- tutorials
- guides
- references
- nonverbal manuals
- online help
- release notes
- glossaries
- tables of contents
- indexes
- web sites
- proposals
- research proposals
- book proposals
- business plans
- internal planning documents
- lab reports
It also has an excellent section on giving presentations. I know that a lot of people in this community present at conferences, so I would recommend that section specifically (even though it has an initial focus on PowerPoint).
IV. EDITING AND PRODUCING DOCUMENTS
This section focuses on editing and the editing process. I think I pulled more useful information on editing from section II, but there is still good information here if you have never been through the process before. The most interesting tidbit I pulled from this section was the following comparison of punctuation to music and timing:
- A comma is a quarter-note rest.
- A dash is a half-note rest.
- A semicolon is a three-quarter note rest.
- A period is a full-note rest.
It's an example that's both meaningful and memorable. I think I've been using dashes incorrectly for the last four years.
The writing style for the book made it enjoyable to read. Rosenberg has a sense of humor and makes a rather dry topic interesting and fun to read. The fact that I read it in one weekend is a testament to that. It typically takes me weeks to work through a book on writing.