[libreoffice-documentation] Help-files: Large-scale 'cosmetic' changes

l10n
#1

Hi,

It is a bad idea to describe the actions of the user in the Help. The Help (as
documentation) should describe only the functionality of the program, but it
is not something that the user can (should) do. Therefore, the words "you",
"your", "user" should be used with extreme caution. Almost always, the
description of the functional can be done without reference to the user. So,
"allows to" (and like this) often can be removed from a sentence.

Best regards,
Lera

#2

Hi Jean Weber,

I disagree, and in fact I wrote a book on the topic (Is the Help
Helpful).

I will read your book, if I can find it in free access. I am always happy to
learn something new. But during about 20 years of developing and support of
programs I have got a habit to believe and focus on standards rather than on
personal opinion.

For Help to be helpful, it often should not be purely
functional but also task-oriented description of what the user can or
should do to achieve a goal or complete a task.

Yes, it is normaly. But it don't contain phrases such as "you can..." or
"allows you to do". Writing tips in the Help is most difficult, because it is
difficult to kipe a good style and show all possibilities.

Best regards,
Lera

#3

Þann fim 17.des 2015 03:43, skrifaði Lera:

Hi,

It is a bad idea to describe the actions of the user in the Help. The Help (as
documentation) should describe only the functionality of the program, but it
is not something that the user can (should) do. Therefore, the words "you",
"your", "user" should be used with extreme caution. Almost always, the
description of the functional can be done without reference to the user. So,
"allows to" (and like this) often can be removed from a sentence.

Best regards,
Lera

There must be a guide of some sort on how to write helpfiles; a HIG it is called in many projects (Human Interface Guidelines).
Most HIGs I've seen, also have clauses on writing style, such as using neutral gender (if possible), almost a third person narrative, and "the computer does not talk to the user" commandment.

In the LibreOffice-design and UX groups there are drafts of our own HIGs [1] [2], and I recall vaguely a discussion on sticking closely to the Gnome HIG [3].

Maybe there are somewhere such guidelines for writing Help, but on the wiki I could only find mostly empty pages under the section HelpAuthoring [4].

Best regards,

Sveinn í Felli

[1]: https://wiki.documentfoundation.org/Design/HIG_foundations
[2]: https://wiki.documentfoundation.org/Design/Principles
[3]: https://developer.gnome.org/hig/stable/
[4]: https://wiki.documentfoundation.org/HelpAuthoring

#4

I'll send you a PDF. My book is more than personal opinion, being based on
research by numerous people over many years. It has been used in technical
writing courses and may still be in use, although it is out of print. --Jean