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

[Sveinn í Felli]

Þ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+unsubscr...@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

[libreoffice-l10n] Re: Many strings in Pootle, LO master, module basic marked as fuzzy

[Baurzhan Muftakhidinov]

ping

On Tue, Dec 15, 2015 at 3:15 PM, Baurzhan Muftakhidinov
 wrote:
> Hi,
>
> Just noticed that about half of the messages
> in LibreOffice master, basic module were marked
> as fuzzy. Browsing through them, I didn't notice any
> change of those original messages.
>
> Were they marked fuzzy by a mistake?
>
> Language code is Kazakh (kk)
>
> Thanks,

-- 
To unsubscribe e-mail to: l10n+unsubscr...@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

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

[Jean Weber]

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

On Thursday, December 17, 2015, Lera  wrote:

> Hi Jean Weber,
>
> В письме от 17 декабря 2015 15:10:40 пользователь 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
>

-- 
To unsubscribe e-mail to: l10n+unsubscr...@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

[libreoffice-l10n] A non-localizable command or translation just not showing up?

[Martin Srebotnjak]

Hi, all,

I just entered this bug report:
https://bugs.documentfoundation.org/show_bug.cgi?id=96573

51RC1 is available on the dev-builds and maybe someone can check if this is
true also for their language/OS and/or confirm the bug.

Thanks,
m.

-- 
To unsubscribe e-mail to: l10n+unsubscr...@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