Re: [libreoffice-l10n] Need for a solid help content

[toki]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1



On 16/12/2015 08:25, Rimas Kudelis wrote:

> Do they charge differently for questions covered in built-in help, or 
what?

Welcome to the wacky world of Help Desks at support centers. Where the
answer is located can have a huge difference on how much the client is
billed. At one establishment I'm familiar with, answers in book number
one were gratis, in book number two cost the client around five bucks
each, and answers from book number the three were charged to the client
for around a grand each.  Answers from «F1» help were not gratis, but
answers from official software documentation manuals were gratis. Beyond
that, I don't remember the rule-set used to determine which answer book
to place new solutions in.

jonathon
-BEGIN PGP SIGNATURE-
Version: GnuPG v2.0.22 (GNU/Linux)

iQIcBAEBAgAGBQJWcdaMAAoJEKG7hs8nSMR78gYP/jjmdNDVETudmOtu/i4Y/kAL
aPYikI5oq0Uc8s0rHMHn+59uxrb0TDo6qUmQ3AwT+JJUEyXcdvYgzNEO0PabAKbg
AUmc5gOzItInmqaBWhQ6VVeVQZokvmvqV2tYgtjKR6O3dD8WFWAZ/pXBF60+IA6w
wJoypTxzjYdrkqwl+m4+2yG+WUNbMkfVKNHmL/Enqo4Ycpc2Gxd9BRJq428y7eb0
8rsJA5ypFJ5KT7Xz7vXptQxhkIUfgwpDsjLxd3DxwLXM7BOL7Ru2YEC7OENwnOK5
PUN0KJCldwi+sXzuD7Pbzip20cXiX7FV6K/ywnAF8DZDuN95AP8M8aqiPTqyPaf4
rPCdgvI+eLfEnTrbLalw9D2IXOezTtP99deKGGnA1uRqjWEAxYluCpRIc2xqtcqQ
0kXsifqRvz8A5CojvUNy6SZpWU4gfSzMK+UAiCGdN0Z9oyu6cmAwZlklvENXH0hl
ugJ8GVexFcPnPGjsWYR5HAlNbQTCNGRleLxRJRScdbOAVnByt88kAZjbZa5GrFwh
AlyP03ZDH7C9VViAvrCle/zx4Ubqwjmm+y0sDGo8V+kGSSGoDZCSYB2gScOg3LaC
F595ODcqTKUoqsxCMQZL3bk6tWHfgV1mgvsPN1bYGUJ3SNDVPGqXfqxdvQaFsJuA
R5U3bfHJxG9+yz1qbu+p
=A2BG
-END PGP SIGNATURE-

-- 
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

[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

В письме от 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: [libreoffice-documentation] Video Tutorial Link in Help

[Tom Davies]

Hi :)
There are some video tutorials at;
http://spoken-tutorial.org/

They cover many different OpenSource programs so if you scroll down
the first drop-down you will see quite a few done for LibreOffice.
The 2nd drop-down allows people to change to a lot of different
languages, although no European ones apart from English.  English
seems to be their starting language which they then get translated
into the many other languages they offer.

Regards from
Tom :)


On 14 December 2015 at 12:42, Yousuf 'Jay' Philips
 wrote:
> Hi All,
>
> Just dropping my two cents on how it could be achieved in the help xml files
> and leaves room for localizers to create related videos, as well as it being
> excluded from localized help not wanted.
>
> Video tutorials links would be added to the "relatedtopics"  found
> at the bottom of help pages and would be added similar to this.
>
> https://youtu.be/Q8V-5yeTHCM;>Video: LibreOffice Overview and
> getting started
>
> Translations where the tutorial shouldnt be seen would have translators
> simply not translate the link text, which would result in the link being
> invisible to those users. This is the simplest means i believe that can
> satisfy all parties/scenarios.
>
> The issue of the video being online and users not having access to the
> internet shouldnt be a barrier to this, as we link to online help as well as
> the extension website which arent accessible without the internet. If a
> company chooses to block youtube and their employees require access to these
> videos, that is an internal matter of the company and this shouldnt penalize
> other users.
>
> An alternative approach for the help xml would require the creation of a
>  tag that handles locales and would require the modification of the
> help viewer to work with it. Below is an example.
>
> 
>  
>xml-lang="en-US">https://youtu.be/Q8V-5yeTHCM;>Video:
> LibreOffice Overview and getting started
>  
> 
>
> Regards,
> Yousuf 'Jay' Philips
>
>
> On 12/10/2015 06:19 PM, Sophie wrote:
>>
>> Hi Robert,
>> Le 10/12/2015 02:07, Robert Alexander a écrit :
>>>
>>> Hi everyone,
>>> thank you all for putting so much consideration into this discussion.
>>>
>>> I am quite happy to independently create tutorial videos for LibreOffice
>>> if
>>> it turns out that this is the best route for the project as a whole. I
>>> was
>>> originally going to do that, but decided it would be good to get in touch
>>> in case you needed specific kinds of tutorials. So whatever happens, my
>>> plan is to make LibreOffice tutorials for the foreseeable future.
>>
>>
>> Thank you very much for that. We have an official TDF channel on YouTube
>> if you are interested to reference or upload your videos there. For now,
>> the only ones that are referenced are those done by
>> TheFrugalComputerGuy, see [1] for Writer for example. In any case, I'm
>> managing the channel for the moment so don't hesitate to poke me.
>>>
>>>
>>> My current workflow means that I create transcripts(technically scripts)
>>> of
>>> my videos, which may be helpful to you as no one will have to go back and
>>> create them if they are needed.
>>
>> ok, for the rest, I let you see with the documentation team. Lera has a
>> very good overview of where the documentation is aiming, so I'm sure you
>> will be able to find a way together.
>>
>>
>> [1] https://www.youtube.com/playlist?list=PL94682FC0D2ADF410
>>
>> Cheers
>> Sophie
>>
>
> --
> To unsubscribe e-mail to: documentation+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/documentation/
> All messages sent to this list will be publicly archived and cannot be
> deleted

-- 
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

[Lera]

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

Re: [libreoffice-l10n] Need for a solid help content

[Rimas Kudelis]

Hi,

2015-12-16 11:05, Michael Bauer wrote:
>
>
> Sgrìobh Sophie na leanas 16/12/2015 aig 08:56:
>> The help on the wiki is exactly the same as the built in help, it's
>> just an export from what you find on Pootle. 
> Seriously? Yikes...

Michael, look on the bright side: at least it's a single set of
information, not two concurrent efforts.

>> As already said numerous times here, the aim is to have the ability
>> to maintain the help in the wiki and still provide on line and off
>> line help. Not everybody has a connection at low cost, not everybody
>> is allowed to access the internet in his work, etc... For the moment,
>> Olivier, Jay, Lera are working on simplifying the use of the help
>> authoring extension, but it's until the remaining technical problems
>> with the export to the wiki are solved. Cheers Sophie 
>
> *to* the wiki? Shouldn't it be the other way round? I have seen
> in-built Help which was essentially a wiki export but never to date
> the other way round, at least not knowingly.


Well, the goal sounds good to me, and if we're moving towards it, that's
fine. I suppose that the content made available for localization is an
export from the English wiki, right? Otherwise, if the content is being
authored externally, and all wikis are just exports of that external
content, I'd say we shouldn't call them wikis at all.

Rimas



-- 
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

Re: [libreoffice-l10n] Need for a solid help content

[Rimas Kudelis]

Hi All,

+1 on what Michael said about help.  I know that traditionally we've had
inbuilt help for a long time, and I know that some feel like it's really
important, but in my opinion, it's more of an emotional factor and
tradition than real need. I especially don't think that maintaining two
sets of help content (one for wiki, one for inbuilt files) independently
makes any sense, and I surely hope we don't do that. If some of us do
that, well, no offence, but in my opinion they're wasting their time. If
"offline help" is so crucial, can't we provide means to download or wiki
as a generated help file, or as a VM instead?

By the way, Oliver, I don't understand why a particular *type* of help
should be mentioned in an SLA at all. Do they charge differently for
questions covered in built-in help, or what? Would anything in the SLA's
have to change drastically if instead of opening the help file F1 would
open a wiki page in a browser?

Rimas

2015-12-13 21:26, Michael Bauer wrote:
> Olivier,
>
> What you wrote makes sense but seems to talk more about the online
> help rather than the inbuilt help. I can think of several commercial
> and OS tools off the top of my head which do not carry inbuilt help
> these days. Going to Help in Trados for example these days redirects
> you to the online Help whereas in the old days, there used to be
> inbuilt Help. Adobe also redirects to F1 user to online Help. MS
> Office only has vestiges of Help left ("Basic Help" in Word for
> example about using the Ribbon). Anything else you need to hit the
> Microsoft website for.
>
> It may be that inbuilt Help was once the norm but I do not think it's
> going to be the norm for much longer and for obvious reasons
> (maintaining it seems to be a bit of a nightmare, in contrast to
> things like wikis).
>
> Don't get me wrong, I'm not suggesting that we need no form of
> documentation. It's just the inbuilt stuff which I personally feel is
> becoming more of a liability than a useful tool in LO. Perhaps
> other/most users *like* inbuilt Help, I don't know, I do not consider
> myself the arbiter of such things, which is why I said it would be
> nice if some research was done. But I get the feeling Help is shifting
> onto the web more and more and if that is the case and if there are
> good reasons, LO should contemplate this.
>
> Michael
>
> Sgrìobh Olivier Hallot na leanas 13/12/2015 aig 19:05:
>> There is a dimension where documentation get critical, and this is in
>> the enterprise and in the development. A software that does not carry
>> proper documentation is subject to several drawbacks. First, the help
>> desk of the enterprise need to get trained into the issues of
>> LibreOffice in the same way they need to addres MSOffice issues. For
>> that they need to know how the software works to assist the users.
>> Docs and references are crucial, together with proper professional
>> support. Second, the help desk is often charged per call. Enterprises
>> where user cannot find proper doc in their own language is facing a
>> higher TCO, because users call HD to get what they don't have at
>> hand. Third, in the way open source is developed and LibreOffice in
>> particular, there are no specs written in the canonical form a priori
>> before implementation (as it was in the OpenOffice.org times under
>> SUN/Oracle) and this is a choice LibreOffice made to offload all
>> hassle of development and rush into coding improvements long due. The
>> trade-off is a bunch of nice features very few know how to work and
>> the curious take much long time to figure it. Forth, by writing the
>> help pages we have a minimum of a reference guide to address bugs and
>> regressions. Without a reference, a regression is allway harder to
>> understand for the developer and the QA guys. Think about shortcut
>> ABC, that suddenty does not work anymore... how can the developer be
>> sure the sortcut was inded supposed to do what ABC was designed
>> originally So, users may not like the help content as we have
>> today and don't like to press F1, but it is our pursuit of quality
>> software to give them the best we can do in terms of documentation.
>> Admitedly our help system is not a piece of literature easy to read
>> (nor is MS Office too), but it must fullfill the mission to establish
>> the landmark of the sofware behaviour. Yes, "RTFM" comes to my mind
>> actually, but there must be an M somewhere. Finaly, other
>> documentation tools like public forums, books, wikis and even Google
>> are all stars of a documentation constellation but almost never
>> figure in a help desk SLA. As more litterature we produce on
>> LibreOffice, the best, because one of the steepest entry barrier we
>> have to propagate LibreOffice is its lack of culture in the office
>> suite marketplace, something MS already achieved long ago and is
>> extremely hard to displace. Of course, there is room for improvement.
>> The nice part of this is that it is well suited for the

Re: [libreoffice-l10n] Need for a solid help content

[Sophie]

Le 16/12/2015 09:25, Rimas Kudelis a écrit :
> Hi All,
> 
> +1 on what Michael said about help.  I know that traditionally we've had
> inbuilt help for a long time, and I know that some feel like it's really
> important, but in my opinion, it's more of an emotional factor and
> tradition than real need. I especially don't think that maintaining two
> sets of help content (one for wiki, one for inbuilt files) independently
> makes any sense, and I surely hope we don't do that. If some of us do
> that, well, no offence, but in my opinion they're wasting their time. If
> "offline help" is so crucial, can't we provide means to download or wiki
> as a generated help file, or as a VM instead?

The help on the wiki is exactly the same as the built in help, it's just
an export from what you find on Pootle.
> 
> By the way, Oliver, I don't understand why a particular *type* of help
> should be mentioned in an SLA at all. Do they charge differently for
> questions covered in built-in help, or what? Would anything in the SLA's
> have to change drastically if instead of opening the help file F1 would
> open a wiki page in a browser?

As already said numerous times here, the aim is to have the ability to
maintain the help in the wiki and still provide on line and off line
help. Not everybody has a connection at low cost, not everybody is
allowed to access the internet in his work, etc... For the moment,
Olivier, Jay, Lera are working on simplifying the use of the help
authoring extension, but it's until the remaining technical problems
with the export to the wiki are solved.

Cheers
Sophie

-- 
Sophie Gautier sophie.gaut...@documentfoundation.org
GSM: +33683901545
IRC: sophi
Co-founder - Release coordinator
The Document Foundation

-- 
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

Re: [libreoffice-l10n] Need for a solid help content

[Michael Bauer]

Sgrìobh Sophie na leanas 16/12/2015 aig 08:56:
The help on the wiki is exactly the same as the built in help, it's 
just an export from what you find on Pootle. 

Seriously? Yikes...
As already said numerous times here, the aim is to have the ability to 
maintain the help in the wiki and still provide on line and off line 
help. Not everybody has a connection at low cost, not everybody is 
allowed to access the internet in his work, etc... For the moment, 
Olivier, Jay, Lera are working on simplifying the use of the help 
authoring extension, but it's until the remaining technical problems 
with the export to the wiki are solved. Cheers Sophie 
*to* the wiki? Shouldn't it be the other way round? I have seen in-built 
Help which was essentially a wiki export but never to date the other way 
round, at least not knowingly.


Michael


--
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