Getting Started 5.1

Hello

In the last weeks I updated the first 4 chapters of the 5.0 Getting
Started book to the 5.1 version and placed them in the 5.1 Draft folder
for revision. The files are with Track changes enabled so it will be
easy to see the changes.

The contents addition are moderately deep in details, bearing that this
is a Getting Started book.

It will be important to revise the contents and the English and give a
feedbak on the job already done.

Thank you in advance

http://www.odfauthors.org/libreoffice/english/getting-started/draft-lo-5.1

Note: The chapters are uploaded, if don't see them then there is an
issue on permissions I need to fix.

I see the folder, but no files.

I just made them "publish internally", which I think will make them
available once logged in...

I've downloaded the preface. I'll have a look at it, mainly for English
and style.

I said this to Oliver directly, forgetting to "reply all":

I don't think it's a good idea to move away from immediacy ("you") to a
more remote tone ("the user"). This goes contrary to current trends in
documentation.

I am also uncomfortable with the change from active to passive voice.
Passive voice is harder to read and to understand, expecially for those for
whom English is not the first language.

Hello Andrew, All

In ODF Authors site, you can get the writing style guide in

Home / LibreOffice / English / Resources for Contributors / Ch5 Style
Guide

I think it worth to all authors to follow it.

Exerpt:

Writing style
The following list summarizes our preferred writing style. Some of these
points are discussed in more detail in the tips for writers, reviews,
and editors starting on page 6.

* Use short, simple, easy-to-understand words and sentences. Be concise
and clear.

* Write in active voice, using passive voice only when necessary or
appropriate. A case of appropriate passive voice is when the focus of
the sentence is on the receiver of an action whose doer is obvious or is
not important. For example, The File dialog box is displayed is OK.

* Use the present tense, using future tense only when necessary or
appropriate. Try to make your descriptions timeless. For example, write
The File dialog box is displayed, rather than The File dialog box will
be displayed. Use future tense only when one event is necessarily later
than another. For example, If you use styles, your documents will be
easier to maintain.

* Avoid over-using you. For example, instead of saying if you want to
have table headers repeat on a new page, you need to do yyy, say to have
table headers repeat..., do yyy.

* When appropriate (as in instructions), use the imperative mood. For
example, instead of you should not use slang, say do not use slang.

* In circumstances where the only alternative to you is the passive
voice, use you. For example, instead of in this window xxx can be done,
say in this window you can do xxx.

* Use gender-neutral language, but don’t use awkward phrases like he or
she to do so. See page 8 for some examples.

Variations of English

For consistency, when writing the user guides we are following US
English spelling conventions and UK English punctuation conventions.

See also “Punctuation” on page 6.
You can use other spelling or punctuation conventions when writing other
documents.

Regards

Olivier

That is good to know. However, in the material I am looking at, the edits
do not seem to follow the style guide. The edits move from active to
passive voice and from direct to indirect speech.

<https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
Virus-free.
www.avast.com
<https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
<#DDB4FAA8-2DD7-40BB-A1B8-4E2AA1F9FDF2>

Hello

You are right.

You must be talking about the Preface. Track changes accept/reject
filtered by author is your friend to put the text on track.

also for quick communication, we have an IRC channel for documentation:
in freenode, access #libreoffice-doc
https://webchat.freenode.net/

regards

I have now put an edited version of the preface in feedback so people
can look at it. I've smoothed things out to improve stylistic consistency, but I'm not doing any more work on this until the
rest of you have agreed on the style issue. I quite like the more formal
tone but I don't like the idea of my time being wasted!

Active voice, direct speech (do this), and use of "you" (but not
over-using "you" or the possessive "your") is standard modern
technical writing in English. All of the books are written that way,
and we should not even consider changing that.

However, some writers (Peter Schofield in particular) tended to
over-use "you" and "your," so I have been changing "your" to "the" in
sentences like "When you have finished editing your image, add it to
your document." becomes "When you have finished editing the image, add
it to the document." He would also write things like, "To print part
of a page, you do [X]" which I have been changing to "To print part of
a page, do [X]" -- the "you" there isn't necessary.

--Jean

From: Jean Weber [mailto:jeanweber@gmail.com]
Sent: Thursday, April 7, 2016 10:38
To: documentation@global.libreoffice.org
Subject: Re: [libreoffice-documentation] Getting Started 5.1

Active voice, direct speech (do this), and use of "you" (but not
over-using "you" or the possessive "your") is standard modern
technical writing in English. All of the books are written that way,
and we should not even consider changing that.

However, some writers (Peter Schofield in particular) tended to
over-use "you" and "your," so I have been changing "your" to "the" in
sentences like "When you have finished editing your image, add it to
your document." becomes "When you have finished editing the image, add
it to the document." He would also write things like, "To print part
of a page, you do [X]" which I have been changing to "To print part of
a page, do [X]" -- the "you" there isn't necessary.

[orcmid]

What about "Complete editing the image and add it to the document" and "Print part of a page is by [X]" or is that what you mean by indirect?

No: what I mean by "indirect" is changing "you can do x" to "the user can
do x". This sort of deflective writing reduces the immediacy of this being
information for the person who is reading it right then.

Hello Olivier,

Can I upload the latest draft Getting Started 5.1 Preface?
I have made a few more change?

Best regards,
Lera

Hi Andrew,

I said this to Oliver directly, forgetting to "reply all":

I don't think it's a good idea to move away from immediacy ("you") to a
more remote tone ("the user"). This goes contrary to current trends in
documentation.

I do not think that the excessive use of "you" is good style. But team has to
decide this.
In any case, I do not see such much of "you" in popular science journals
(which have been writing really beautiful and plain language) and technical
documentation (that does not use "you" never).

PS: I am not native English speaker, of course.

Best regards,
Lera

Look at the first page of the preface.

Same here. Folder with no files.

Cheers,
Sylvia

Sylvia, have you logged in?

Everybody, the attached file is a screenshot of what I mean. The existing
text says "You", which is direct and immediate, and is NOT the overuse of
"you" people have been talking about. The proposed change is "Everybody",
which is indirect and distant. It does not catch the reader the same way as
the original does.

I am beginning to think somebody heard "we say 'you' too much" and just
decided to get rid of "you" everywhere. The only places that need work are
where the text says something like "You then push the red button...", where
"You" is obviously not needed.

a