Writing Quality of User Guides

Documentation General
#1

After comments from Robert about the Base chapter and its poor quality, I checked this chapter and have to agree with Robert. It is very poorly written, composed and formatted.

The problem is how do we improve the writing quality of LibreOffice user guides and make them look more professional and match a very good application for office software.

I do have one solution and that is to use Simplified English. It is not simple English and was developed to cover the following points:

The English language is the most spoken language in the world and is widely understood on all continents. Just like any other language, the English language continually evolves and words are added (or lost) frequently, resulting in over 75 dialects and variations. To control the English language and reduce its complexity, Simplified English was developed covering the following points:

  • Help non-English speakers understand words more easily.
  • Help professionals with quicker translations into other languages.
  • Make the documents easier to understand using a limited vocabulary.
  • Develop a set of writing rules for creating user guides.
  • Create a list of approved words and technical terms for use in user guides. Each word or technical term has only one approved definition.

I do have knowledge of Simplified English because I have used it for several large international companies during my career as a Technical Writer. I can develop a Simplified English writing guide for use by all the LibreOffice volunteers. The main problem in creating this guide is the development of a list of approved words and technical terms.

Please let me know your thoughts on my suggestion.

Regards
PeeWee

#2

This is a correction to my previous message. I should have read it properly before hitting the send button. SORRY

After comments from Robert about the Base chapter and its poor quality, I checked this chapter and have to agree with Robert. It is very poorly written, composed and formatted.

The problem is how do we improve the writing quality of LibreOffice user guides and make them look more professional and match a very good application for office software.

I do have one solution and that is to use Simplified English. It is not simple English and was developed to cover the following points:

To control the English language and reduce its complexity, Simplified English was developed covering the following points:

  • Help non-English speakers understand words more easily.
  • Help professionals with quicker translations into other languages.
  • Make the documents easier to understand using a limited vocabulary.
  • Develop a set of writing rules for creating user guides.
  • Create a list of approved words and technical terms for use in user guides. Each word or technical term has only one approved definition.

I do have knowledge of Simplified English because I have used it for several large international companies during my career as a Technical Writer. I can develop a Simplified English writing guide for use by all the LibreOffice volunteers. The main problem in creating this guide is the development of a list of approved words and technical terms.

Please let me know your thoughts on my suggestion.

Regards
PeeWee

2 Likes
#3

HI @PeeWee

Thank you for your suggestion. I think a writing guide on Simplified English will be an valuable asset for our community.

Further more, I guess it will greatly help in translating our guides into other languages, reaching much larger community by making easier to communities absorb LibreOffice culture. Correct me if I’m wrong, I foresee progressive use of machine translation if we use Simplified English as source (if not perfect, a lot of typing can be spared).

I all in for further discussion on the subject and I can provide support, but I’m not a English native speaker.

Cheers
Olivier

PS: I religiously follow advise by @jeanweber in the style guide, available in Style Guide - The Document Foundation Wiki . Is Simplified English related to it?

#4

Hello Olivier

Thanks for the support, but it is something that has to be done.

Simplified English (SE) is mainly used by the aviation industry, but there are other international companies that use versions of SE. I do have a copy of the SE standard for aviation, but this is over 400 pages long and far too detailed to be useful for a LibreOffice SE Guide. The solution is to develop a version for LO and I will be using Jean’s writing style guide as a starting point. The aviation SE standard will be used for some of the rules to modify the writing style guide.

The basic rules are as follows:

  • US English is the language used.
  • Develop a dictionary of approved words and technical terms. This does require discussion.
  • Do not use descriptive noun clusters.
  • Do not use the possessive apostrophe. For example - Peter’s pen (the pen belonging to Peter). Yes it does lengthen sentences, but it is necessary for understanding.
  • Do not use word contractions. For example - don’t (do not); can’t (cannot or can not); isn’t (is not).
  • Do not use Latin abbreviations - e.g (for example); etc (and so on); i.e. (that is)
  • Sentences are limited to 25 words. Occasionally, a sentence can be longer.
  • Paragraphs are limited to 6 sentences. Occasionally, a paragraph can have more sentences, if necessary for explanation. Sentences using a colon are counted as two sentences.
  • List items are limited to one sentence about one point or procedural step. A 2nd sentence can be added for explanation.

There are more rules which will be in the first draft of the LibreOffice SE Writing Guide.

Regards
PeeWee

#5

Hello Peter,

Very interesting thread!

Simplified English (SE) is mainly used by the aviation industry, but there are other international companies that use versions of SE.

I just saw this on the Simplified English wiki page!

I know of Plain Language - which is used in many industries. I actually think that the guide for writers at LO does follow many of the Plain Language principles. Maybe upgrading the guide to include more Plain Language principles is a good option?

This conversation is extremely timely since the ISO actually published its first Plain Language Standard on June 23 2023:

  1. Press release
  2. ISO Standard on Plan Language (sadly no access to it)
  3. International Plain Language Federation webpage and its page regarding the new ISO Standard

Best
Nay

#6

Hello Nay and Olivier

I have been looking at Simplified English standards and the ASD-STE100 is the only I can download for free. I do have an account that allows me to download this standard because of my previous technical writing in the aviation industry. To work fully with this standard, an SE Editorial team would have to be setup, which to me is a no go for LibreOffice. Doing SE editorial work is a full time job.

My solution is to extract the necessary bits of information and rules, then combine it with the work produced by Jean. It will take time to do this.

The biggest problem is developing a dictionary of approved words and technical terms. This is necessary so that an LO SE writing guide works for all LO volunteers. The benefit would be the same words are used throughout all LO user guides.

Watch this space.
Regards

Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team

2 Likes

Impressum (Legal Info) | Datenschutzerklärung (Privacy Policy)   Content on this site is licensed under a Creative Commons Attribution Share Alike 3.0 license.