Date: prev next · Thread: first prev next last
2015 Archives by date, by thread · List index


Þ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


В письме от 16 декабря 2015 19:15:44 пользователь Tom Davies написал:
Hi :)
Again i am asking for advice and suggestions.  I don't know the best
way to handle this or even if there is a real problem here or not.


It is about the Help Files.  The Documentation Team may be able to
make some much-needed changes to the help-files.  However, it is to
solve a problem that only exists in English.  For all other languages
it is, beyond doubt, already corrected purely through the translation
process.

Is there a system or tool that allows such sweeping changes without
marking completed translations as incomplete?

I think there was some discussion about developing such a tool but i
imagine it would be extremely difficult to make something like that.
So i would be surprised if there is anything yet.


The problem is that the help files often say "allows to", which is bad
grammar (at best) and may even be nonsensical or misleading in
English.  Even in English (US).  Bad grammar is often fine in emails
because we can usually be a bit forgiving and figure out what is
likely to be meant.


The 2 currently proposed ways of correcting this are;

1.  A "broad brush strokes" sweeping change to "search and replace" to
replace it with something like "allows you to", which is not a perfect
fit for all circumstances but is mostly "good enough".  It's not
always clear who "you" refers to but mostly it's fairly clear or the
ambiguity is tolerable.  There are a few cases where the sweeping
change is just as confusing or nonsensical but it hides the problem in
the majority of cases.

2.  A careful and detailed re-phrasing of each occurrence
individually.  This will take a long time and requires a lot of very
intensive work.  It's would be very similar to doing a lot of
translations - from geeky-English to English.

3.  A hybrid of the first two.  Option 1 and then followed by option
2.  This gives us a "quick fix" improvement to start with and then the
detailed corrections later.


You may have better ideas.  This may be similar to a problem you have
had to solve and you may have experience of what works best.  Please
let the documentation team know.

The additional problem is that changing the English version might well
have a negative impact on all or most of the translations.  That is
the main problem i hope we can solve without too much pain.

Many regards from
Tom :)




--
To unsubscribe e-mail to: l10n+unsubscribe@global.libreoffice.org
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/l10n/
All messages sent to this list will be publicly archived and cannot be deleted

Context


Privacy Policy | Impressum (Legal Info) | Copyright information: Unless otherwise specified, all text and images on this website are licensed under the Creative Commons Attribution-Share Alike 3.0 License. This does not include the source code of LibreOffice, which is licensed under the Mozilla Public License (MPLv2). "LibreOffice" and "The Document Foundation" are registered trademarks of their corresponding registered owners or are in actual use as trademarks in one or more countries. Their respective logos and icons are also subject to international copyright laws. Use thereof is explained in our trademark policy.