Help-files: Large-scale 'cosmetic' changes

I disagree, and in fact I wrote a book on the topic (Is the Help
Helpful). 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.

Jean Weber

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

Þ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

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

Free copy of PDF available here:
http://www.jeanweber.com/newsite/wp-content/uploads/ITHH_Ebook.pdf

Hi Tom,

Tom Davies píše v St 16. 12. 2015 v 19:15 +0000:

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.

I don't think it is terribly difficult to create such a tool, the
problem is running it - it has to by done by an admin with the access to
Pootle, so doing it string by string for each such much needed (but for
other languages cosmetic) change would be rather sub-optimal.

But - what about to introduce an 'en_US' translation in the Pootle,
where native speakers could improve the wording without changing the
meaning? Then once per the release cycle, these could be copied back in
a way that it marks no translations fuzzy.

[Again - this does not cover those who download the .po files from
Pootle, and then upload back; but hopefully with a proper communication,
giving them enough time to upload their work before such a change, this
could be less of a problem too?]

Does that work?

All the best,
Kendy

Tom (and others),

I'm not sure that "allow to" is such an enormous problem with the help
files. There are only 8 help files which use "allow to" or "allows to", and
only one of them has more than one occurrence, so manual change is easily
possible - no automation needed.

A far larger problem is the API documentation where the problem is
widespread. Clicking at random I found
http://www.openoffice.org/api/docs/common/ref/com/sun/star/bridge/Bridge.html
at the first attempt! And I can't think of a way in which "allows to
initialize" could be changed to "initializes" automatically.

As to whether "you" should be allowed in a help file, I have no deep
feelings - this appears to be contentious, but is used a lot in some files.
As there is a human being using the help file, I see no harm in referring to
them as "you". As it happens "allows you to" also occurs in at least one
help file. But I do not think that "you" has a place in API documentation -
there is no human being involved in calling a method or using an interface
(or is it the programmer?).

Jean Weber wrote

Free copy of PDF available here:
http://www.jeanweber.com/newsite/wp-content/uploads/ITHH_Ebook.pdf

Dear Jean,

I get an error 404 from this link.

Peter

Jean,

I tried again and got this again:

Not Found
The requested URL /newsite/wp-content/uploads/ITHH_Ebook.pdf was not found on this server.
Additionally, a 404 Not Found error was encountered while trying to use an ErrorDocument to handle the request.

I don't think it's my browser (Firefox) as the message seems to come from your server.

Best regards,

Peter
mailto:lo@ptoye.com
www.ptoye.com

Hi Peter,

try this
www.jeanweber.com/books/ITHH_Ebook.pdf

Kind regards
Regina

ptoye schrieb:

Thanks, Regina, for posting the correct link before I had a chance to
check it. I would edit my earlier note if I could!
--Jean

Thanks Regina - got it.

I have to admit that at 249 pages it's not going to be my bedtime reading,
though

Now I've read through the book (not in detail) I think it's great, but as it
deals mostly with the principles behind help page design rather than details
of style it's not all that relevant to my personal issue.

But I do note that you approve of pages where "you" is used.

Hi :slight_smile:
Sorry!! I feel really bad about all that! :frowning:

Yes. Go ahead. :slight_smile:

I did ask the international translators mailing list and there were some
suggestions and discussion but there didn't seem to be any conclusion.

So the international translators have been told there might be many
re-wordings, for a large number of strings, that will significantly improve
the English without affecting the clearly intended meanings of the
strings. Apparently the quality of all the translations is currently FAR
higher than the quality of the English original! This appears to be due to
the long-term lack of resources invested in the English "built-in help".
As i understand it the tiny team of people who do work on it are not normal
native-English speakers and their other commitments within the LibreOffice
project all combine to make it remarkable that the quality is as high as it
is. That quality has made it relatively easy to translate, apparently, but
feedback from normal (is not devs!) English (US, Uk and the rest) people
has largely been that they find it difficult or even impossible to
understand.

Peter, your original suggestion of doing high-quality changes on a string
by string basis would probably be the best way to proceed. Steve's
suggestion of using search&replace to get the whole lot done up to a medium
quality all in one go very quickly, and then going back individual strings
to bring them all up to your higher-quality later is probably best
abandoned even though that was the suggestion i was pushing for.

Many, many thanks for taking my advice to heart and holding off for so
long, and for still being willing to do the improvements!! :))

Also, many apologies for my failure to respond any sooner! :frowning:

Regards, thanks and good luck from
Tom :slight_smile:

More precisely, it is the result of a deliberate policy to _not_ have a
formal team to translate the strings into English.

As such, whenever somebody decides to clean up the English translation,
were the translators paid normal translation rates, it would cost
roughly US$1,000 per string, per location, regardless of any change in
the target language.

What should happen is:
Source document: Whatever variant of English/Pidgin the devs, etc. write in.

Target Document:
* French;
* German;
* Spanish;
* English;
etc;

jonathon

TomD,

Thanks for all of this. I must say that is was a bit disheartening to be first welcomed into the community and then left dangling for 3 months. Especially as now the days are getting longer I don't have the dark evenings to work at it. And I'm also in the throes of buying a house, which will take up quite a bit of time. So I may not be able to get things done may not move as quickly as I would have in December.

I agree with you about the problems of non-native English speakers. As English is the common language of computing most people in the field have a good grasp of the language. But written technical English is very different from spoken or emailed English, and I suspect that inaccurate teaching doesn't help. In short, what's needed is an editing process whereby a native speaker can remove issues before they're published. If only.....

[Short digression - if you look at the manuals which come with some East Asian equipment, LO documentation comes over as a model of clarity and accuracy. One such document tells me that using the equipment may be fatal. It's for a TV set and the programmes aren't usually that bad.]

Oh well, now I've got that off my chest, I can start looking at the workflow for modifying the texts. I gather that I have to learn git and gerrit first :frowning:

Best regards,

Peter
mailto:lo@ptoye.com
www.ptoye.com

Hi Peter,

Sorry I didn't follow the all thread (difficult to read and get its
context, also)

TomD,

Thanks for all of this. I must say that is was a bit disheartening to
be first welcomed into the community and then left dangling for 3
months. Especially as now the days are getting longer I don't have
the dark evenings to work at it. And I'm also in the throes of buying
a house, which will take up quite a bit of time. So I may not be able
to get things done may not move as quickly as I would have in
December.

Sorry to hear that you didn't get feedback on our side, I'm sure Olivier
will be able to help you for now on, and great that you're still there :slight_smile:

I agree with you about the problems of non-native English speakers.
As English is the common language of computing most people in the
field have a good grasp of the language. But written technical
English is very different from spoken or emailed English, and I
suspect that inaccurate teaching doesn't help. In short, what's
needed is an editing process whereby a native speaker can remove
issues before they're published. If only.....

Are you talking about the guides or the help?

[Short digression - if you look at the manuals which come with some
East Asian equipment, LO documentation comes over as a model of
clarity and accuracy. One such document tells me that using the
equipment may be fatal. It's for a TV set and the programmes aren't
usually that bad.]

Oh well, now I've got that off my chest, I can start looking at the
workflow for modifying the texts. I gather that I have to learn git
and gerrit first :frowning:

You don't need to learn git or gerrit to contribute to the
documentation, it's only if you want to, but this is absolutely not
needed. What would be your preferred area to contribute?
Cheers
Sophie

Hi Sophi,

It's a bit confusing as there are two threads involved here. The first one is http://nabble.documentfoundation.org/Use-of-quot-allow-to-quot-in-documentation-td4167829.html but a second thread got started about "cosmetic" changes. Does this help you? Most of my comments really should be in the original thread.

I'm really talking about the help files, which is where I started. I can have a look at the guides to see if they have the same or similar problems. But one project at a time please!

Best regards,

Peter
mailto:lo@ptoye.com
www.ptoye.com

Hello Peter

If you are comfortable with the help files, then the bug#80430 [1] has a
list of missing help files that LibreOffice need.

Everything written for the help files can (and will) be reused in the
Guides books and vice versa, modulo some adjustments. There is a big
overlap of contents between the two media.

Contents for documentation, either text or media is much needed at the
moment. Pick one of the open blocking bugs listed in [1] and write a
text document covering the topic. I must admit there is a game of
googling around to get the sources of the topic, in order to compose a
usefull help page.

[1] https://bugs.documentfoundation.org/show_bug.cgi?id=80430

Kind regards

Olivier

Hi :slight_smile:
Yes! I totally agree.

Most people joining the documentation team are restricted to only working
on the Published Guides. Although there is a long wish-list of other
documentation that needs to be worked on and a long wish-list of things
people who have been in the team have wanted to work on. Often those
overlap but there are significant blockers preventing the much-needed work
from being done, as in the case of the 'in-built' help.

Sometimes people's best possible contribution is to do a bit to erode those
blockers. Getting discussion going often reveals more information about
the blockers and suggestions arise on how to deal with them.

For example i had no idea that you would have to lean Git nor that we would
probably need to set-up and handle a 'new language' - although i suspected
the later might be the case and i could see that blocking the whole thing.

There is a free course to help learn Git (and many other things) over at
Codecademy;
https://www.codecademy.com/learn/learn-git
You can register yourself so there is no innate blocker there. I tend to
find there time estimates are woefully inadequate for me so their claim it
takes "2 hours" would probably take me 6 months, unless i could sit down
and really focus for that 'long' (in which case it might only take an
hour). I tend to register with at least 2 addresses so that on at least
one run-through i can apply their lessons to a 'real case' outside of their
website.

As for the setting up and administration of running a 'new' language i
think that's a discussion we need to take to the international translators
mailing list. Whether it is best to do that before or after (or both)
making some of the one-off changes to one or a few strings is something we
wont know until after it's been done! I was rather hoping that by copying
my recent reply to you to the international translators mailing list that
they might suddenly start organising an elegant answer, or at least start
re-discussing the issues.

Anyway, you are not expected to fulfil your offer of helping out with this
because we/I have failed to live up to our end of the bargain. Many
apologies for that! :frowning:
Regards from
Tom :slight_smile: