chapter 1

Please consider the following suggestions:

This
document is Copyright © 2012 by its contributors as listed below. You may distribute it
and/or modify it under the terms of the Creative Commons
Attribution-ShareAlike 3.0 Unported license
(http://creativecommons.org/licenses/by-sa/3.0/),
version 3.0 or later.
The "and/" should be deleted since it does not add anything and is basically useless.  In a law document, it is useless.

The phrase "A and B" excludes all else and means   "both A and B".  The phrase "A or B" is inclusive and means, A, B, or both A and B.
Who we
are and what we do
The
LibreOffice Documentation team is a group of volunteers who strive to
provide high quality guides for LibreOffice users and developers. You
can become part of the Documentation team by contributing to one or
more of our many projects. No matter what your level of experience
is, you can make a valuable contribution.

If you wish to imply that the group succeeds in writing high quality guides, take out strive.

Also, the word "provide" is an overused word that is imprecise.  Use "produce" instead.

Examples
of current projects:
  * User guides
  * Tutorials and how-tos
  * Blog
  * Quick reference cards
  * Assist with writing and editing as requested by Website and Help teams
Examples
of planned projects:
  * Administrators’ guide
  * BASIC Programmers’ guide
  * Technical writers’ / power users’ guide

There should be no space before or after the  "/"

The words "Examples of" do not add anything, are imprecise and should be deleted.,

Some
tasks can be quickly and easily without extra logins, much knowledge
of LibreOffice, or a lot of time or long-term commitment. These are
described on the Easy
Hacks page of the wiki and later in this chapter.

Two problems here, passive and no verb.  Rewrite as:
Some tasks do not require extra logins.  . . .   These tasks are . . . .

  * Mailing list – Most of our day-to-day communication takes place on the mailing list. To sign up for the list, send a blank e-mail message to documentation+subscribe@global.libreoffice.org and follow the instructions that will be mailed back to you.
The dash after list should not have spaces before or after unless that is what is prescribed in your style sheet.

Generally main clauses of a technical document should be written in the present tense.  Thus, the sentence should read:  ". . .  and follow the instructions mailed back to you."  The phrase "that will be" adds nothing.

  * Wiki – Go to the wiki and create an account for yourself; the Create Account link is in the upper righthand corner of each wiki page.

Delete "hand"   It is extra and therefore redundant and useless.

  * ODFAuthors – Ask on the mailing list for an administrator to create an account for you.
  * Blog – Ask on the mailing list for a blog administrator to create an account for you.
Word order is awkward.  Better "On the mailing list, ask . . . ."

  * Most members of the documentation team will not need a login for the main LibreOffice website. If you do (for example, if you’re helping the Website team by reviewing or editing pages), ask on the Website mailing list for instructions on how to do this.Change "will not need a login for the main LibreOffice website" to "probably will not to log in to the main . . ."

Here, you are talking about future use, so "will + verb" is OK.  However, direct writing uses action verbs, and better to make it a probabilistic statement rather than an absolute statement.

Don't
feel confident of your writing skills or your level of knowledge
about OpenOffice.org itself? Reviewing documentation (especially docs
aimed at new users) is a great way to start. Is it written well for
the audience? Are the instructions correct? Is anything missing? Let
us know what needs fixing, or correct it yourself.

Better as "If you don't feel confident about your . . . ," you can help by reviewing . . . ."   Combine the sentences to make an overall more descriptive and clear statement."

All of the  headings "writing, editing, reviewing, maintenance" and descriptions of the activities under them should be parallel in structure for clarity.

Sign
up, introduce yourself on the list, tell us a bit about your
experience and what interests you.
What
to read:
  * Relevant chapters of this Contributors’ Guide (some are specialized topics that you may not need to know; you can skip them).
  * The Documentation Development page on the wiki and linked pages including Easy Hacks.
What
to do:
  * Choose what you’d like to work on. You are welcome to ask for guidance on the list.
  * For user guides: Follow instructions in Chapter 2 of this Guide to download and install the chapter template and write or review chapters. See other chapters for information on writing style, use of paragraph and characters styles in the template, and so on.
  * For blogging, see Chapter 4 of this Guide.
Instead of "What to read" and "What to do"  use "Please read" and "Please do the following."  Let's please be polite.

Don,
You can get an account on the wiki and fix things yourself. I encourage you to do so. Otherwise, it's unlikely to get done because no one has time to do it. For me at least, it's a much lower priority than fixing the documents made available to users. So I am always delighted when someone else does the job. Please? Many thanks if you will!

--Jean

Hi :slight_smile:
I agree with most of that except

1.  Most non-mathematicians seem to mean xor when they say "or".  So for most people "A or B" excludes "A and B" happening a the same time. 
2.  without spaces on both side of "/" it makes things a little cramped and difficult to read.  Also does;
Technical writers’/power users’
mean
writers’/power
so that writers and power are interchangeable there or should
"Technical writers"
be put in speech marks or something to keep the 2 words together and similarly with "Power users"?  I think it might be best to swap out the / and replace with an "or" or an "and/or"

However, one of the advantages with wiki-editing is that
1.  People are free to re-edit later
2.  you can experiment and if it looks right then keep it, there is even a "preview" option that can help with experimentation
3.  people can look at the history to see changes and see how things are developing

So, i think just "go for it".  All your ideas have merit and almost all are things i either agree with or don't mind either way.  So it's almost always an improvement imo.  As Jean says, go for it :) 
Regards from
Tom :slight_smile:

Please consider the following suggestions:

This
document is Copyright © 2012 by its contributors as listed below. You may distribute it
and/or modify it under the terms of the Creative Commons Attribution-ShareAlike 3.0 Unported license (http://creativecommons.org/licenses/by-sa/3.0/), version 3.0 or later.
The "and/" should be deleted since it does not add anything and is basically useless. In a law document, it is useless.

My first reaction was to think, "yes, style guides have always
instructed to avoid 'and/or'." Then I looked at the current edition of
the APA Style guide (the one applicable to my own work) and found that
there had been a change in recommendations since the edition I had on my
shelf.

The phrase "A and B" excludes all else and means "both A and B". The phrase "A or B" is inclusive and means, A, B, or both A and B. Who we are and what we do
The
LibreOffice Documentation team is a group of volunteers who strive to
provide high quality guides for LibreOffice users and developers. You
can become part of the Documentation team by contributing to one or
more of our many projects. No matter what your level of experience
is, you can make a valuable contribution.

If you wish to imply that the group succeeds in writing high quality guides, take out strive.

Just my two cents but the documents are collectively produced by (not
provided) by a large number of individuals with varying degrees of
expertise in technical writing. My sense is that most individuals are
trying to communicate some complex ideas in a way that can be understood
by anyone who picks up the document. Individuals can succeed in writing
high quality documents (the word "succeed" referring to "writing") but
the quality of the content, how understandable (I know that's not a
proper word) it is to people of different backgrounds--that's not as
easy to evaluate as the quality of the writing. In light of that, it
makes sense to me to say that the team strives to provide high quality work.

Also, the word "provide" is an overused word that is imprecise. Use "produce" instead.

Once the documents are produced, they are provided to the community.
Perhaps the word choice should be "to" versus "produced."

Examples of current projects:
  * User guides
  * Tutorials and how-tos
  * Blog
  * Quick reference cards
  * Assist with writing and editing as requested by Website and Help teams
Examples of planned projects:
  * Administrators’ guide
  * BASIC Programmers’ guide
  * Technical writers’ / power users’ guide

There should be no space before or after the "/"

Formatting wise, the spaces come in handy.

The words "Examples of" do not add anything, are imprecise and should be deleted.,

Actually, they do add something. Without the words you have a closed
group (guides, tutorials, etc.). With the words, you have a subset of a
larger group yet to be defined. This gives the message that if there is
a subject, not on that list, that someone would like to take on as a
project, it would become part of that list.

As noted, you are free to go in and make any changes yourself but don't
be surprised if someone comes in after you and corrects your changes.

Hi :slight_smile:
I agree with most of that except

1. Most non-mathematicians seem to mean xor when they say "or". So for most people "A or B" excludes "A and B" happening a the same time.
2. without spaces on both side of "/" it makes things a little cramped and difficult to read. Also does;
Technical writers’/power users’
mean
writers’/power
so that writers and power are interchangeable there or should
"Technical writers"
be put in speech marks or something to keep the 2 words together and similarly with "Power users"? I think it might be best to swap out the / and replace with an "or" or an "and/or"

Yes, it would be better to not employing the forward slash (/) at all and use "or" instead.

In addition, LO does not employ hyphenation in its PDF or ODT documentation, so "words" with enclosed slashes tend to be unnecessarily long--making the formatting appear lousy at those times when much unused white space results on account of a forward slash near a line end.

Gary