On 9/13/2013 5:38 AM, Tom Davies wrote:
Hi :)
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
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 :)
________________________________
From: Jean Weber <[email protected]>
To: Don Welty <[email protected]>
Cc: "[email protected]"
<[email protected]>
Sent: Friday, 13 September 2013, 5:03
Subject: Re: [libreoffice-documentation] chapter 1
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
On 13/09/2013, at 9:57, Don Welty <[email protected]> wrote:
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
[email protected] 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.
--
To unsubscribe e-mail to: [email protected]
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
