Links

Tags

Recent tweets

Campus visit - how to improve technical writing skills

Earlier this week I was honoured to be a guest lecturer at York University. A few years ago, I made contact with Professor Franck van Breugel who teaches a master’s level course in computer science. Franck was interested in improving the quality of his student’s writing skills. Franck, like me, understands that being able to write or communicate well are important skills to take into any career.

So for the third year in a row, I met with Franck’s class and presented a slideshow created by Roger Sanders that corresponds with his upcoming book “From Idea to Print”. Roger used the slides as the basis for a full day writing workshop on how to create and publish technical documents. I’ve modified the slides so that I can teach them in a little more than an hour and touch on the basics of how to improve writing skills.

What are the basics?

1. Schedule time to write. If you wait until you’re “in the mood to write”, you’ll never get anything done! Set goals for how much you want to accomplish and move to another section if one is causing you grief. Reward yourself as targets are reached.

2. Have a strong outline before you start to write. I know it sounds cliché, but the more up front planning you do, the easier the writing will be. Even for technical documents, you should “tell a story”. Have a beginning, say a problem that needs to be solved; a middle, the search for a solution; and an end, a strong conclusion.

3. Let some personality show through in the writing. There are some cases where dry, factual writing is required, but where it’s not, let the writing be conversational or slightly casual to be of interest to the reader. Always think of your reader. Even if the writing is just for a school paper, the last thing you want to do is to bore the reader so that the ending is never reached.

4. Diagrams and tables are useful, but ONLY if they are tied tightly with the text. Don’t put them there just for filler because they’ll never be looked at. The best idea is to add reference numbers to the diagrams and have text to lead the reader from one point to the next. If that sounds like too much work, maybe the diagram isn’t really needed.

5. No one’s writing is perfect… every author needs to review and revise their work many times. Most authors get quite tired of reading what they’ve written by the time it is “finished”.

To make revision as easy as possible, I suggest that each time you go through your draft, look for one specific thing at a time. For instance, the first time through, check that you are using the active voice instead of passive. Next, go through and look to make sure headings and lists use parallel wording. Next, look for words that are commonly spelled incorrectly that will not be caught by a spell checker. And so on.

6. For everyone, but especially if you are English-second language, consider reading the text out loud or have the computer read it to you. You may be able to hear problems in the wording easier than you can read them. Also, look at past comments you’ve received on writing assignments. Likely you often make the same errors every time you write, so pay close attention to how your previous errors were corrected, and go through your document to specifically focus on improving these problem areas.

7. For the past month I’ve been acting as a judge on the “DB'2’s Got Talent” competition on the “DB2Night Show”. Much of the advice here about writing also came out on that show in terms of improving the quality of a technical presentation. Even if you don’t fully understand the topic being discussed (as was true for me many times) you’ll be able to see what makes a presentation “good”.

8. There are a lot more details that will help you, so I encourage you to get a copy of Roger’s book when it is published. One last piece of advice. If you’re writing a technical document, your goal is not to make it “beautiful”… your goal is clarity. You want to ensure that anyone who reads what you’ve written understands your technical messages.

After the lecture, I found out that Sam Lightstone had recently visited the campus to give career advice similar to what he wrote in his book “Making it Big in Software”. Apparently he had a massive audience and Prof Franck told me that the students were buzzing with excitement after the talk. Sam is recording a podcast to be featured on Safari Books Online. Once I have the details, I’ll post here.