×
Namespaces

Variants
Actions
(Difference between revisions)

Things to remember when writing Help text or Manuals

From Nokia Developer Wiki
Jump to: navigation, search
kiran10182 (Talk | contribs)
m (Help moved to Things to remember when writing Help text or Manuals: The original heading was quite ambiguous.)
mayankkedia (Talk | contribs)
Line 1: Line 1:
Have you ever played a game where your partner tries to draw an object according to your instructions? S/he can't obviously see the object your holding and you can't see what s/he has drawn so far. It's quite challenging, actually. Much harder than it sounds!
+
[[Category:Usability]][[Category:Mobile_Design]]
 +
Help manuals are written keeping in mind the end user, who mostly likely would not be that conversant with the technical complexities of the implementation. Which brings us to the <b>first golden rule</b> of writing help manuals “Do not use technical jargons or overwhelm the user with details of underlying technicalities of the functionalities”.
  
When writing help texts and manuals you should remember that what you say can be comprehended quite differently than you expect. I once read instructions for removing a blade from a cutter. I tried to remove it but I couldn't complete the task. I asked a friend to remove it. He didn't do it like I did but still couldn't get the blade off. The person who had written the instruction ment to do it yet in another way! So, one instruction, three ways of understanding it.[[Category:Usability]]
+
The user is not bothered about the nitty-gritties; rather s/he wants to use the application without too much fiddling around, which brings us to the <b>second golden rule</b>. “The steps, process, ways to use the application or its functionalities should be written/documented in simple, easy to understand language”.
 +
 
 +
Lesser the maintenance/after sales support a product requires, better are the Return On Investment for the parent company, in which lies the <b>third golden rule</b>. “A well written help manual could very easily from an end user perspective be the best/worst part of the product/service offering.”
 +
 
 +
<b>There is no substitute for a specialist</b>, which means if the product being developed has lot of functionalities and you want the end user to actually make use of those offerings, you should always consider hiring/taking the services of a technical writer. The technical writer comes with an end user perspective, as ideally speaking s/he hasn’t been associated with the code/design of the product. So when they see the product they think of it from the eyes of a user, his/her comfort level and familiarity with the product offerings. This understanding helps them formulate the help manual in a manner which is easy to follow and use.
 +
 
 +
Some of the phases of writing a help manual should be:-
 +
 
 +
1. <b>Understanding the target user profile</b>
 +
 
 +
Before even beginning to look at the product offering or writing a single word in the help manual, the writer should understand who the end users of the product are. They should delve into the likely skill-sets, comfort level, expectations, usage patterns, linguistic/cultural profile of the target user.
 +
 
 +
The first two would help in deciding how much information needs to be provided. The next two would help in formulating the help in a way where the most common used functionalities/expected behaviors to be documented more clearly and in greater details. While the last two would decide the languages that the help manual needs to be written in, also to use words/expressions/grammar and other linguistic things in accordance with the user, because some words/sentences might make complete sense to someone in say the US while it could end up offending someone in India.
 +
 
 +
2. <b>Analyzing the working of the product in detail</b>
 +
 
 +
Typically the individual writing the help manual should understand all the functionalities/offerings/any known issues/limitations of the product as this would help them articulate the same properly so that the user doesn’t have to spend sleepless nights making repeated calls to after sales/support groups. The writer should sync up with the architect/product manager of the application to understand the application in detail. One to one sessions/walk throughs could be a good way of doing this activity.
 +
 
 +
3. <b>Creation of a user friendly layout/format for the help manual</b>
 +
 
 +
The layout/stylesheet of the help manual should be user friendly and easy on the eyes. It should be formal yet attractive enough for someone willing to look through them. A typical end user is very irritable when it comes to spending too much effort to get something working, hence the importance of using the right layout/fonts/colors to give the user a sense of purpose and helpfulness.
 +
 
 +
<i>Some generic guidelines to follow are:-</i>
 +
 
 +
# Generally a pictoral representation of the features/settings is more informative and easy to follow then words.
 +
# Maintain consistency of fonts and layout throughout the help manual
 +
# Use colors sensibly ensuring that you don’t use too loud colors, or any colors that could possibly offend/irritate the reader’s sensibilities.
 +
# Use fonts in line with the intent of the product, for instance a game/fun application could use fonts like Comic Sans, Monotype Corsiva etc, where-as an application targetted for enterprises should typically use Times New Roman, Arial etc as fonts.
 +
# Ensure that the layout fits well into the limited visible space available on the mobile devices.
 +
 
 +
 
 +
4. <b>Writing the actual content of the help manual</b>
 +
 
 +
Having finalized the layout/format of the manual, you get down to the actual wording of the help manual. Make sure that you don’t overwhelm the user with too much content or give too less information thinking the user would be smart enough to read between the lines.
 +
 
 +
<i>Some generic guidelines to follow during this activity are:-</i>
 +
 
 +
# Clearly detail the settings/expected values on the settings/administrator pages if the application has any.
 +
# Document the maximum/minimum values for the input fields so that the user is aware of them before-hand.
 +
# Clearly mention the known issues if any before hand so that the user doesn’t expect something to work when it is not going to in any case.
 +
# Link the logical entities of the help together for instance in a multi view application it is always a good idea to write the help for all the functions/commands available on a particular view.
 +
# In case the help for a particular view also completes a feature on another view, give links to that instead of re-writing the entire thing again.
 +
# Use the right wordings, carefully detailing the steps and expected behavior, sometimes an example setting and the expected results would help the user to understand better.
 +
# Do not use slangs or wordings with religious/racial/sexual/ethnic connotations. Remember the intent is to help and not to hurt/peeve the end user.
 +
# Share the support center contact details in case the user is not able to make headaway even after using the help.
 +
 
 +
 
 +
5. <b>Review, both peer and end-user</b>
 +
 
 +
Get the contents reviewed by your peer in case you have one, otherwise the product manager/architect could also be a good choice for the reviewer. It would also be advisable to ask an end user/someone not involved in the product development/help content writing process to review the artefacts. The latter would bring in fresh ideas and end user perspectives thereby helping finetune/improve the document even better.
 +
 
 +
6. <b>Final delivery along with the product</b>
 +
 
 +
Once you have done all this, you are ready to deliver the help manual along with the product, either as an online help tool, end user documentation/manual or a context sensitive help.
 +
 
 +
For more on packaging context sensitive help.
 +
 
 +
<b>Edited by - Mayank on 10/06/2009</b>
 +
 
 +
== Link ==
 +
 
 +
[[Context-sensitive Help Basics]]
 +
 
 +
[[CS000809 - Implementing context-sensitive help]]

Revision as of 15:08, 10 June 2009

Help manuals are written keeping in mind the end user, who mostly likely would not be that conversant with the technical complexities of the implementation. Which brings us to the first golden rule of writing help manuals “Do not use technical jargons or overwhelm the user with details of underlying technicalities of the functionalities”.

The user is not bothered about the nitty-gritties; rather s/he wants to use the application without too much fiddling around, which brings us to the second golden rule. “The steps, process, ways to use the application or its functionalities should be written/documented in simple, easy to understand language”.

Lesser the maintenance/after sales support a product requires, better are the Return On Investment for the parent company, in which lies the third golden rule. “A well written help manual could very easily from an end user perspective be the best/worst part of the product/service offering.”

There is no substitute for a specialist, which means if the product being developed has lot of functionalities and you want the end user to actually make use of those offerings, you should always consider hiring/taking the services of a technical writer. The technical writer comes with an end user perspective, as ideally speaking s/he hasn’t been associated with the code/design of the product. So when they see the product they think of it from the eyes of a user, his/her comfort level and familiarity with the product offerings. This understanding helps them formulate the help manual in a manner which is easy to follow and use.

Some of the phases of writing a help manual should be:-

1. Understanding the target user profile

Before even beginning to look at the product offering or writing a single word in the help manual, the writer should understand who the end users of the product are. They should delve into the likely skill-sets, comfort level, expectations, usage patterns, linguistic/cultural profile of the target user.

The first two would help in deciding how much information needs to be provided. The next two would help in formulating the help in a way where the most common used functionalities/expected behaviors to be documented more clearly and in greater details. While the last two would decide the languages that the help manual needs to be written in, also to use words/expressions/grammar and other linguistic things in accordance with the user, because some words/sentences might make complete sense to someone in say the US while it could end up offending someone in India.

2. Analyzing the working of the product in detail

Typically the individual writing the help manual should understand all the functionalities/offerings/any known issues/limitations of the product as this would help them articulate the same properly so that the user doesn’t have to spend sleepless nights making repeated calls to after sales/support groups. The writer should sync up with the architect/product manager of the application to understand the application in detail. One to one sessions/walk throughs could be a good way of doing this activity.

3. Creation of a user friendly layout/format for the help manual

The layout/stylesheet of the help manual should be user friendly and easy on the eyes. It should be formal yet attractive enough for someone willing to look through them. A typical end user is very irritable when it comes to spending too much effort to get something working, hence the importance of using the right layout/fonts/colors to give the user a sense of purpose and helpfulness.

Some generic guidelines to follow are:-

  1. Generally a pictoral representation of the features/settings is more informative and easy to follow then words.
  2. Maintain consistency of fonts and layout throughout the help manual
  3. Use colors sensibly ensuring that you don’t use too loud colors, or any colors that could possibly offend/irritate the reader’s sensibilities.
  4. Use fonts in line with the intent of the product, for instance a game/fun application could use fonts like Comic Sans, Monotype Corsiva etc, where-as an application targetted for enterprises should typically use Times New Roman, Arial etc as fonts.
  5. Ensure that the layout fits well into the limited visible space available on the mobile devices.


4. Writing the actual content of the help manual

Having finalized the layout/format of the manual, you get down to the actual wording of the help manual. Make sure that you don’t overwhelm the user with too much content or give too less information thinking the user would be smart enough to read between the lines.

Some generic guidelines to follow during this activity are:-

  1. Clearly detail the settings/expected values on the settings/administrator pages if the application has any.
  2. Document the maximum/minimum values for the input fields so that the user is aware of them before-hand.
  3. Clearly mention the known issues if any before hand so that the user doesn’t expect something to work when it is not going to in any case.
  4. Link the logical entities of the help together for instance in a multi view application it is always a good idea to write the help for all the functions/commands available on a particular view.
  5. In case the help for a particular view also completes a feature on another view, give links to that instead of re-writing the entire thing again.
  6. Use the right wordings, carefully detailing the steps and expected behavior, sometimes an example setting and the expected results would help the user to understand better.
  7. Do not use slangs or wordings with religious/racial/sexual/ethnic connotations. Remember the intent is to help and not to hurt/peeve the end user.
  8. Share the support center contact details in case the user is not able to make headaway even after using the help.


5. Review, both peer and end-user

Get the contents reviewed by your peer in case you have one, otherwise the product manager/architect could also be a good choice for the reviewer. It would also be advisable to ask an end user/someone not involved in the product development/help content writing process to review the artefacts. The latter would bring in fresh ideas and end user perspectives thereby helping finetune/improve the document even better.

6. Final delivery along with the product

Once you have done all this, you are ready to deliver the help manual along with the product, either as an online help tool, end user documentation/manual or a context sensitive help.

For more on packaging context sensitive help.

Edited by - Mayank on 10/06/2009

Link

Context-sensitive Help Basics

CS000809 - Implementing context-sensitive help

115 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×