Tip of the month from PRC
 February 1999

Writing user friendly OR with correct grammar?

Published 10 February 1999
Revised 27 February 1999 with the questionnaire RESULTS

We accept Mastercard/Eurocard/Maestro/JBC and Visa!
Tip of the month is edited by Peter Ring, PRC (Peter Ring Consultants, Denmark)
- consultants on how to write user friendly manuals 
If you have corrections, better texts or suggestions for improvements, please let me know . 

This tip is based on an idea from Debbie Abbott, Sr. Technical Writer, Smallworld Systems, Inc. Englewood, Colorado, USA.

I know it is "a bit" controversial, and I have consequently decided to make it in a different way this time: I present you to a problem, and then I ask you to vote for the best solution. Ready?

Contents

Is correct grammar always user friendly?

Honestly - No!

Maybe to the trained linguists, who has got all the rules on his/her spine, and get horrified by any break of a rule to such an extent, that further reading is blocked.

But to the average reader, who has other things than the grammar book in mind, I have an idea that it's sometimes a bit doubtful. Let's take a few examples to illustrate the problem:

Example 1:

In HTML certain characters are described by tags with the format "&<content>;". For example an "&" is to be written "&amp;".

Here I broke a rule, because I should have written: ... with the format "&<content>;." For example an "&" is to be written "&amp;."

But then a lot of programmers would write the tag with a full stop included as "&amp;." - and that's not correct!

And even worse: UK and US rules are different:

To me the British style is user friendly, but the American style is bad!

Example 2:

In languages like German and Danish, we build long words without a hyphen inside. For example week-end would be weekend. Some of these words may contain 3, 4 or 5 parts, and sometimes if you split the word wrongly when reading (like wee-kend if wee and kend were both accepted words), you get the most peculiar results.

Example three:

In English (UK and US) small numerals (<100 and at least <10) should in principle be written out with letters. But in many cases, that's not user friendly. What is most easy to read? Do you think a bad reader (e.g. an ESL) will agree with you? Furthermore, to most non-English speaking people, this rule is not only impractical, it's to some extent ridiculous because you are making things more difficult than necessary, and of course they use the numerals directly without breaking any rules.

A possible solution?

If you want to break one or a few of these simple rules, specify that in the "How to read this manual" chapter, explaining why you have deliberately chosen to break the rule.

Example:

We know very well the American English grammar, but in this manual we have decided to break one of the rules because sticking to the rule would in certain cases confuse the reader. The rule we will use in this manual is:

Questionnaire

Processed on 27 February 1999.

Results

Summary
Conclusion
Statistics
Comments (separate page)

We received 44 filled in questionnaires from 8 (9?) countries:

Australia 3
Canada 3
Denmark 1
Germany 2
Israel 9
Japan 1
UK 2
USA 22
(none) 1 (US .com address, but could be located abroad)
The reason for the relatively many answers from Israel is most likely the very active Israelic TECH-SHORET mailing list.

Summary:

The low number of answers makes it impossible to make sharp conclutions, but the following conclusions are statistically fairly significant:

In rounded figures: 80% of the answers indicated a willingness to accept deviations from the rules for the sake of user-friendlyness, of which around 60% without any comments and 20% with a comment. 20% would stick to the rules no matter what.

The acceptance level was the same for writers with a bachelors degree as for writers with a masters degree, but more respondents more with a masters degree preferred some sort of a comment.

The acceptance level was lower for writers with a linguistic degree than for the rest of the writers.

There were very little difference in the acceptance of other writers deviations form the rules and own deviations from the rules.

Many of the "yes" comments indicated, that the "How To" solution would probably not help anybody and even confuse some of the readers.

Conclusion

You can deliberately break some grammatical rules or generally accepted style book rules in order to make the text better understood. But be aware that some people, mainly academics and linguists will love to flog you for it. If you are doing contract work, make sure your client agrees with your decision. Peter Ring, M.Sc.EE, B.Com., PRC

Statistics

The main questions gave the following answers:
 

Accept written by others
Accept for own writing
Yes 24 65% 22 59%
Yes with a How To comment  5 14% 6 16%
Yes with Another solution 2 5% 2 5%
No 6 16% 7 19%
n.a. 7 - 7 -

44 100% 44 100%

The distribution by education level gave the following answers (multiple answer possible):
 

Answers % Yes Yes HowTo Yes Another No Total
Masters degree 14 27% 6 2 1 3 12
- in %

50% 17% 8% 25% 100%
Bachelors degree 30 58% 17 3 0 6 26
- in %

65% 12% 0% 23% 100%
No degree 4 8% 2 1 1

n.a. 4 8%




Total 52 100%




The distribution by type of education gave the following answers (multiple answer possible):
 

Answers % Yes YesHowTo YesAnother No Total
Linguistic education 14 27% 8 1 0 4 13
- in %

62% 8% 0% 31% 100%
Technical education 11 21% 6 2 1 1 10
- in %

60% 20% 10% 10% 100%
Other education 19 37% 11 3 0 2 16
- in %

69% 19% 0% 13% 100%
No degree 4 8% 3 0 1 0 4
n.a. 4 8% 4


4
Total 50 100%




Click here to read all the comments.

If you disagree with these ideas - or have other relevant points, experiences, or idea +/-, please e-mail me !

Ideas for new "Tip of the month" subjects are VERY welcome, too!

Go to last month's tip .
Go to a list of old tips .
Return to the User Friendly Manuals' homepage .

Free update service
Click here if you want to receive an e-mail whenever this website is updated with major new information, e.g. with a new "tip of the month" or a new interesting link. The e-mail will briefly describe the content of the update.

.

.

.

.

.

.

.