How to write a good email feedback (for Help)

This post is here to explain how to properly write an email feedback for the Delphi Help system. So often people assume that nobody reads these emails. This leads to emails with little value to us (the Documentation team). Next I am going to describe what is a documentation feedback email, who reads those, why should you care and how to write them properly.

What is a feedback email:

  • It’s an email in which you tell us what we did wrong.
  • In the recent versions of the RAD Studio Help  at the bottom of the page you can see a “Send us feedback” link.
  • Pressing of that link will open up a new message window (with your email client). That mail contains some information about the topic in which you pressed the “Send us feedback” link.
  • You’re supposed to leave that information in the body, and add a few lines of description.

Why write feedback emails (aka “Why should you care”):

  1. It helps us identify the topics which are more important to our readers.
  2. Some topics are out of date or need some notes. Suggesting that in the feedback email helps us complete these topics with more precise “field” information. If you have more free time on your hands you can even suggest fixes for topics.
  3. You as a consumer of the help may know better which articles would need better “See Also” links.
  4. It generally takes less than one minute to wrote us an email.

Who is looking at them:

  • A person in the documentation team.  Usually the emails are processed once a month (it may be longer).
  • The QA step is performed by the person in the documentation team and the bug is registered in the internal bug-tracker directly.

How to write a feedback email:

  1. Leave the subject intact and keep the information in the body of the mail. By removing that information you make the life of the person reviewing that email a lot harder.
  2. Be specific. Emails that say “all the help is bad” are discarded immediately. If you’re targeting  more articles, be sure to specify that.
  3. Be sure that the email targets a documentation problem. Bugs in the product should be entered through QC. You’re not going to get an answer if you ask a non-documentation related question.
  4. If you are using a localized Help (French, German or Japanese), write about the problem in English. People reading these feedback emails do not know all the languages.
  5. Try to refrain from inflammatory phrases. It’s not that pretty to read people using curse words. These mails are sometimes discarded directly.
  6. Mails that simply praise Delphi 7 help and nothing more are discarded (no informational value).

Note for people using older help versions (like 2006, 2007). A lot of bugs in those versions have already been fixed. I would suggest you download newer versions at http://docs.embarcadero.com (you can get a CHM file for example).

You May Also Like

About the Author: Alexandru Ciobanu

7 Comments

  1. It depends on how much time you have and whether you want to track the progress of the bug in QC afterward. Although sending an email is faster IMO.

  2. “Be specific. Emails that say “all the help is bad” are discarded immediately”

    “Mails that simply praise Delphi 7 help and nothing more are discarded”

    Within the confines of what you are trying to achieve (putting lipstick on pigs?) I can understand both your sensitivity and the request for specific information.

    However the Help system as supplied with D2009 is one of the reasons why my company has made the decision to abandon Delphi as a programming tool and I would have thought that should be of interest to you, even though it is unspecific. It is one of several steps backward that have changed Delphi from RAD to SAD.

    Less is sometimes more.

  3. Thanks for the info. I was glad to find chm help files. However, the links to chm help for Help Update 1 are all broken, e.g.

    Not Found

    The requested URL /docs/radstudio/delphiAndcpp2009/HelpUpdate1/EN/chm/devcommon.chm was not found on this server.
    Apache/2.2.3 (CentOS) Server at docs.embarcadero.com Port 80

  4. @Dino – shame that no one in the high management actually reads these mails so your point of view is unnoticed by the people who can actually take a conclusion from your mail.

    @Max – better wait for Update 2 to come out (nearing).

  5. Documentation feedback is very important in any company’s attempt to reach out to and connect with their customers. Ultimately, IMO, the onus needs to be on the company to make it as easy as possible for users to submit feedback. Finding ways to let the user be less specific is actually a good thing, because it further reduces the need for users to spend a lot of time writing feedback. A recent post of mine might be of interest: http://blog.lugiron.com/2009/05/documentation-feedback-dont-ask-if-you-dont-care/

  6. Thanks for you opinion. Actually we’re processing all email (specific or not). While I outlined some specific details I would want to see, any feedback is actually greatly appreciated!

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.