Thursday, April 12, 2012

Technical writing FAQ

Here are some frequently asked questions (with Vince's answers).

Reading
Q: What should I read in order to become a good technical writer? How about newspapers written in English?
A: Yes, I suggest newspapers or anything you enjoy reading. I also suggest you find and read online journals in your field. Here are some good links http://bit.ly/SEjrnls to get your started (Please note: http://bit.ly/SEjrnls opens a "feed" of links in "Twitter". You can "follow" one or more of these journals if you are a Twitter user. Otherwise, just go to the journal's website and subscribe via RSS or however you like to read online content.)

Q: Do you have any tips for taking what I have read into my writings efficiently?
A: Keep a journal handy at all times. Then, use the phrases you have collected in your daily writing. I use the following tools to collect useful bits of language:
  • Free dictation software (Dragon) on iPhone (the voice recognition software often makes mistakes, but you can edit them before emailing to yourself)
  • Voicemail on Skype (When away from a notebook, I call myself to leave a quick message. Later, I listen to it to remind myself of the idea or phrase.)
  • IC recorder (Olympus Voice Trek V-72)
  • Notepad (digital or paper-based)
  • Note cards

Feedback
Q: When I use incorrect English, how can I get correction from others?
Q: How can I review what I have written?
A: Vince's admissions consulting clients use a variety of tools, including:

EMAIL
Subject Line
Q: I noticed that the subject line of e-mails from Japanese always begin with the word "about," for example, an e-mail from a colleagues in my lab, "about meeting and cleaning." I think it's because Japanese used to write "について" when writing an e-mail in Japanese. However, the Kaplan tells us the best rule of thumb of writing a subject line is to be specific. My question is: is the word "about" in the example redundant, making the subject line not specific? Would it become better if he wrote "meeting and cleaning?"
A: I am not qualified to advise you on writing Japanese emails. As for English, I like the following answer:
A: Use a detailed subject line. Business executives often complain that email with subject lines that are vague or empty land in their junk mail folder. Avoid getting ignored by including a straightforward but thorough subject.

A: You can make it even easier for your recipient to immediately understand why you’ve sent them an email and to quickly determine what kind of response or action it requires. Compose a great “Subject:” line that hits the high points or summarizes the thrust of the message. Avoid “Hi,” “One more thing…,” or “FYI,” in favor of typing a short summary of the most important points in the message:
Lunch resched to Friday @ 1pm
Reminder: Monday is "St. Bono’s Day"–no classes
REQ: Resend Larry Tate zip file?
HELP: Can you set up my printer?

In fact, if you’re relating just a single fact or asking one question in your email, consider using just the subject line to relate your message. As I’ve mentioned before, in some organizations, such emails are identified by adding (EOM)—for end of message—at the end of the Subject line. This lets recipients see that the whole message is right there in the subject without clicking to the view the (non-existent) body. This is highly appreciated by people who receive a large volume of mail, since it lets them do a quick triage on your message without needing to conduct a full examination.
Sadly, good email subjects have become something of a lost art, especially among more recent additions to the Interweb. It’s a pity, because you’re far more likely to get a favorable response from a busy person when they can quickly understand your message.

The Start
Q: While addressing the recipient, is it better to use Sir/Madam instead of Mr./Ms./Dr. followed by the name of the recipient?
Q: How should I write the title (Mr., Ms.) of recipients if I do not know his or her sex? Many non-English names are difficult to distinguish their gender just by their names.
Q: How can I write to a foreign company without knowing who is in charge of a certain section? In the Kaplan chapter 3, there is a part saying we should follow their customs of reading while writing for international audiences. But in general, which style should we follow when we are not sure whether the person we are writing to is a foreigner?
A:
  • Dear Sir or Madam: (use if you don't know who you are writing to)
  • Dear Personnel Director: (use if you only know someone's title but not his or her name)
  • Dear Dr, Mr, Mrs, Miss or Ms Smith: (use if you know who you are writing to, and have a formal relationship with - VERY IMPORTANT use Ms for women unless asked to use Mrs or Miss)
  • Dear Frank: (use if the person is a close business contact or friend)

A: Say hello. Business email has become so informal that some people do not even begin with a salutation. Avoid this habit. Properly address the person you are writing and use a colon, rather than a comma. For example, "Dear Mr. Smith:" is a correct business opening. You can switch to a comma once back-and-forth correspondence is established.

The Reference
Q: How should I do my self introduction in emails or letters?
A:
  • With reference to your advertisement in the Times...
  • With reference to your letter of 23rd March...
  • With reference to your phone call today...
  • Thank you for your letter of March 5th.

Q: What form is the proper way to self introduce myself to you in this email for making questions concerning the contents of the class last week?
A: I am listing various ways students contacted me in order of preference (best first; try to avoid the last two)
  • Dear Professor Ricci
  • Dear Mr. Ricci
  • Dear Mr. Vince Ricci
  • Dear Ricci sensei
  • Dear Mr. Vince
  • Dear Sir

The Reason for Writing
Q: How should I state the purpose of my contact?
A:
  • I am writing to inquire about
  • I am writing to apologize for
  • I am writing to confirm

Understand why you’re writing
Before you type anything into a new message, have explicit answers for two questions:
  • Why am I writing this?
  • What exactly do I want the result of this message to be?
If you can’t succinctly state these answers, you might want to hold off on sending your message until you can. People get dozens, hundreds, even thousands of emails each day, so it’s only natural for them to gravitate toward the messages that are well thought-out and that clearly respect their time and attention. Careless emails do not invite careful responses.
Think through your email from the recipient’s point of view, and make sure you’ve done everything you can to try and help yourself before contacting someone else. If it’s a valuable message, treat it that way, and put in the time to making your words count.(found at http://www.43folders.com/2005/09/19/writing-sensible-email-messages; accessed 11/2010)

Requesting
Q: How do I ask for what I need in a polite way?
A:
  • Could you possibly...?
  • I would be grateful if you could...

Get what you need
Although the possible topics and content of messages are theoretically endless, I’d propose that there are really just three basic types of business email.
  1. Providing information - “Larry Tate will be in the office Monday at 10.”
  2. Requesting information - “Where did you put the ‘Larry Tate’ file?”
  3. Requesting action - “Will you call Larry Tate’s admin to confirm our meeting on Monday?”
It should be clear to your recipient which type of email yours is; don’t bury the lede. Get the details and context packed into that first sentence or two whenever you can. Don’t be afraid to write an actual “topic sentence” that clarifies a) what this is about, and b) what response or action you require of the recipient.
Since the Larry Tate meeting on Monday has been moved from the Whale Room, could you please make sure the Fishbowl has been reserved and that the caterer has been notified of the location change? Please IM me today by 5pm Pacific Time to verify.
Assume that no one will ever read more than the first sentence of anything you write. Making that first sentence strong and clear is easily the best way to interest your recipient in the second sentence and beyond.(found at http://www.43folders.com/2005/09/19/writing-sensible-email-messages; accessed 11/2010)

What’s the action here?
If your message includes any kind of request—whether for a meeting, a progress update, or what have you—put that request near the top of the message and clearly state when you will need it. Do not, under any circumstances, assume that your overwhelmed recipient will take the time to sift through your purple prose for clues about what they’re supposed to be doing for you.
Depending on the style of your team and the volume of mail they create, you might even consider adding functional text headers to the top of the body outlining the exact nature of the message.
This email is:
[ ] actionable
[ ] fyi
[ ] social


Response needed:
[ ] yes
[ ] up to you
[ ] no


Time-sensitive:
[ ] immediate
[ ] soon
[ ] none

Remove the guesswork from your messages by thinking of them like friendly work orders; you must not be afraid to ask for what you want, especially if you have any desire to actually have the recipient give it to you.(found at http://www.43folders.com/2005/09/19/writing-sensible-email-messages; accessed 11/2010)

Giving Bad News
Q: How should I manage expectations of readers to understand that something bad has happened?
A:
  • Unfortunately...
  • I am afraid that...

Enclosing Documents
Q: How do I reference attachments?
A: Most people prefer that documents be sent as attachments, rather than copied and pasted into the body of the email.
  • I am attaching...
  • Please find attached...
  • Attached you will find...

Closing Remarks
Q: How do I close my letter in a direct but polite way?
A:
  • Thank you for your help. Please contact us again if we can help in any way.
  • Thank you for your help. Please contact us again if there are any problems.
  • Thank you for your help. Please contact us again if you have any questions.




- Updated by Vince on Fri 12 Aug 2016
  • I have been a full-time international graduate admissions consultant since 2002
  • Based in Tokyo, Japan, I help clients around the world
  • In 2007, I launched VincePrep because I wanted to help the best candidates aiming for the top schools
  • To share my insights with a talented team, I rejoined Agos as Consulting Director in 2014
  • Now, I lead 10 professionals who deliver Japan’s best graduate admissions results
  • I also serve as Board President of The Association of International Graduate Admissions Consultants (AIGAC)
  • Given my ongoing professional and personal commitments, I accept very few clients
  • Usually, I refer prospects to one of my highly-experienced and successful colleagues
  • If interested, please complete this intake form
  • Meanwhile, please explore my YouTube channel, and be sure to subscribe for the latest updates
  • Thank you for your interest, and best wishes for your success!

Monday, April 2, 2012

Typical structure of a journal article

Typical structure of a journal article


Title

first idea of what it's about

Abstract

brief summary: purpose, method, findings, conclusions. Emphasize the original contributions.

Introduction

purpose of study, a statement of your hypothesis or specific question to be explored, how it fits with previous research

Method/Procedures

how the study was carried out

Findings/Results

what was found

Discussion/Conclusion

what was learned and how it can be applied to future research


Suggested Order For Writing:

The easiest way to determine your main idea and contribution is by writing your discussion section first. After confirming your terminology and methods, write your conclusion. Write the introduction next. Finally, use the topic sentence from each paragraph and create an abstract. If your abstract does not capture your purpose, method, findings, conclusions, and original contributions, rewrite your topic sentences.





- Updated by Vince on Fri 12 Aug 2016
  • I have been a full-time international graduate admissions consultant since 2002
  • Based in Tokyo, Japan, I help clients around the world
  • In 2007, I launched VincePrep because I wanted to help the best candidates aiming for the top schools
  • To share my insights with a talented team, I rejoined Agos as Consulting Director in 2014
  • Now, I lead 10 professionals who deliver Japan’s best graduate admissions results
  • I also serve as Board President of The Association of International Graduate Admissions Consultants (AIGAC)
  • Given my ongoing professional and personal commitments, I accept very few clients
  • Usually, I refer prospects to one of my highly-experienced and successful colleagues
  • If interested, please complete this intake form
  • Meanwhile, please explore my YouTube channel, and be sure to subscribe for the latest updates
  • Thank you for your interest, and best wishes for your success!

Sunday, April 1, 2012

Use a cautious or tentative style in academic writing


Cautious or tentative style


It is wise to use a cautious tone in your writing, because very often you are discussing issues in which there is no absolutely right answer, or absolutely correct definition, or absolutely perfect solution. If you present something as being the best way, it might easily be shown not to be the best way. Therefore, it is usually better to 'suggest', rather than 'state. 

Here are some phrases that convey a cautious tone.


                                   
1.
Introductory verbs:
e.g. seem, tend, look like, appear to be, think, believe, doubt, be sure, indicate, suggest
2.
Certain lexical verbs
e.g. believe, assume, suggest
3.
Certain modal verbs:
e.g. will, must, would, may, might, could
4.
Adverbs of frequency
e.g. often, sometimes, usually
5.
Modal adverbs
e.g. probably, possibly, perhaps, conceivably (compare with less tentative adverbs like certainly, definitely, clearly)
6.
Modal adjectives
e.g. probable, possible (compare with less tentative adjectives like certain, definite, clear)
7.
Modal nouns
e.g. assumption, possibility, probability
8.
That clauses
e.g. It could be the case that .
e.g. It might be suggested that .
e.g. It appears that .    
e.g. It may be that .
e.g. It is likely that .
e.g. This suggests that .
9.
To-clause + adjective
e.g. It may be possible to obtain .
e.g. It is important to develop .
e.g. It is useful to study .


Saturday, March 10, 2012

How to write email messages that get results


Understand why you’re writing

Before you type anything into a new message, have explicit answers for two questions:
  • Why am I writing this?
  • What exactly do I want the result of this message to be?

If you can’t succinctly state these answers, you might want to hold off on sending your message until you can. People get dozens, hundreds, even thousands of emails each day, so it’s only natural for them to gravitate toward the messages that are well thought-out and that clearly respect their time and attention. Careless emails do not invite careful responses.
Think through your email from the recipient’s point of view, and make sure you’ve done everything you can to try and help yourself before contacting someone else. If it’s a valuable message, treat it that way, and put in the time to making your words count.


Subject Line


Q: I noticed that the subject line of e-mails from Japanese always begin with the word "about," for example, an e-mail from a colleagues in my lab, "about meeting and cleaning." I think it's because Japanese used to write "について" when writing an e-mail in Japanese. However, the Kaplan tells us the best rule of thumb of writing a subject line is to be specific. My question is: is the word "about" in the example redundant, making the subject line not specific? Would it become better if he wrote "meeting and cleaning?"



A: I am not qualified to advise you on writing Japanese emails. As for English, I like the following answer:

A: Use a detailed subject line. Business executives often complain that email with subject lines that are vague or empty land in their junk mail folder. Avoid getting ignored by including a straightforward but thorough subject.



A: You can make it even easier for your recipient to immediately understand why you’ve sent them an email and to quickly determine what kind of response or action it requires. Compose a great “Subject:” line that hits the high points or summarizes the thrust of the message. Avoid “Hi,” “One more thing…,” or “FYI,” in favor of typing a short summary of the most important points in the message:

Lunch resched to Friday @ 1pm
Reminder: Monday is "St. Bono’s Day"–no classes
REQ: Resend Larry Tate zip file?
HELP: Can you set up my printer?


In fact, if you’re relating just a single fact or asking one question in your email, consider using just the subject line to relate your message. In some organizations, such emails are identified by adding (EOM)—for end of message—at the end of the Subject line. This lets recipients see that the whole message is right there in the subject without clicking to the view the (non-existent) body. This is highly appreciated by people who receive a large volume of mail, since it lets them do a quick triage on your message without needing to conduct a full examination.


Sadly, good email subjects have become something of a lost art. It’s a pity, because you’re far more likely to get a favorable response from a busy person when they can quickly understand your message.





The Start


Q: While addressing the recipient, is it better to use Sir/Madam instead of Mr./Ms./Dr. followed by the name of the recipient?
Q: How should I write the title (Mr., Ms.) of recipients if I do not know his or her sex? Many non-English names are difficult to distinguish their gender just by their names.

Q: How can I write to a foreign company without knowing who is in charge of a certain section? In the Kaplan chapter 3, there is a part saying we should follow their customs of reading while writing for international audiences. But in general, which style should we follow when we are not sure whether the person we are writing to is a foreigner?



A: Say hello. Business email has become so informal that some people do not even begin with a salutation. Avoid this habit. Properly address the person you are writing and use a colon, rather than a comma. For example, "Dear Mr. Smith:" is a correct business opening. You can switch to a comma once back-and-forth correspondence is established.

A:
  • Dear Sir or Madam: (use if you don't know who you are writing to)
  • Dear Personnel Director: (use if you only know someone's title but not his or her name)
  • Dear Dr, Mr, Mrs, Miss or Ms Smith: (use if you know who you are writing to, and have a formal relationship with - VERY IMPORTANT use Ms for women unless asked to use Mrs or Miss)
  • Dear Frank: (use if the person is a close business contact or friend)







The Reference


Q: How should I do my self introduction in emails or letters?
A:
  • With reference to your advertisement in the Times...
  • With reference to your letter of 23rd March...
  • With reference to your phone call today...
  • Thank you for your letter of March 5th.



Q: What form is the proper way to self introduce myself to you in this email for making questions concerning the contents of the class last week?
A: I am listing various ways students contacted me in order of preference (best first; try to avoid the last two)
  • Dear Professor Ricci
  • Dear Mr. Ricci
  • Dear Mr. Vince Ricci
  • Dear Ricci sensei
  • Dear Mr. Vince
  • Dear Sir




The Reason for Writing


Q: How should I state the purpose of my contact?
A:
  • I am writing to inquire about
  • I am writing to apologize for
  • I am writing to confirm












Requesting

Q: How do I ask for what I need in a polite way?
A:
  • Could you possibly...?
  • I would be grateful if you could...






Get what you need

Although the possible topics and content of messages are theoretically endless, I’d propose that there are really just three basic types of business email.
  1. Providing information - “Larry Tate will be in the office Monday at 10.”
  2. Requesting information - “Where did you put the ‘Larry Tate’ file?”
  3. Requesting action - “Will you call Larry Tate’s admin to confirm our meeting on Monday?”


It should be clear to your recipient which type of email yours is; don’t bury the lede. Get the details and context packed into that first sentence or two whenever you can. Don’t be afraid to write an actual “topic sentence” that clarifies a) what this is about, and b) what response or action you require of the recipient.


Since the Larry Tate meeting on Monday has been moved from the Whale Room, could you please make sure the Fishbowl has been reserved and that the caterer has been notified of the location change? Please IM me today by 5pm Pacific Time to verify.


Assume that no one will ever read more than the first sentence of anything you write. Making that first sentence strong and clear is easily the best way to interest your recipient in the second sentence and beyond.

 



What’s the action here?


If your message includes any kind of request—whether for a meeting, a progress update, or what have you—put that request near the top of the message and clearly state when you will need it. Do not, under any circumstances, assume that your overwhelmed recipient will take the time to sift through your purple prose for clues about what they’re supposed to be doing for you.

Depending on the style of your team and the volume of mail they create, you might even consider adding functional text headers to the top of the body outlining the exact nature of the message.


This email is:
[ ] actionable
[ ] fyi
[ ] social


Response needed:
[ ] yes
[ ] up to you
[ ] no


Time-sensitive:
[ ] immediate
[ ] soon
[ ] none



Remove the guesswork from your messages by thinking of them like friendly work orders; you must not be afraid to ask for what you want, especially if you have any desire to actually have the recipient give it to you.

 




Giving Bad News
Q: How should I manage expectations of readers to understand that something bad has happened?
A:
  • Unfortunately...
  • I am afraid that...




Enclosing Documents
Q: How do I reference attachments?
A: Most people prefer that documents be sent as attachments, rather than copied and pasted into the body of the email.
  • I am attaching...
  • Please find attached...
  • Attached you will find...




Closing Remarks
Q: How do I close my letter in a direct but polite way?
A:
  • Thank you for your help. Please contact us again if we can help in any way.
  • Thank you for your help. Please contact us again if there are any problems.
  • Thank you for your help. Please contact us again if you have any questions.



Compiled from various online sources including

http://esl.about.com/cs/onthejobenglish/a/a_basbletter.htm; accessed 1/2011
http://www.ehow.com/print/how_2075198_write-business-email.html; accessed 1/2011
http://www.43folders.com/2005/09/19/writing-sensible-email-messages; accessed 1/2011


Saturday, January 7, 2012

Slides

Here are Vince's slides.
View more presentations from VincePrep
Vince's NOTE: to view these slides in full-screen or download (requires login), please open this page http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 You can also view Vince's other presentations here http://bit.ly/VincePresents
Audio for November 2010 lecture is here



Featured Post

What are the five reasons to use passive voice?

USE ACTIVE VOICE As listed below, there are only 5 reasons one should EVER use passive voice. If you don't need to use passive voi...