translation-quick-start-guide into Japanese
by Noriko Mizumoto
Hi
I have finished Japanese translation of the above.
Also the translation has been proofread by Mr. Tatsuo Sekine.
How can I publish this?
cheers
noriko
17 years, 8 months
active, passive, and ... commanding
by Karsten Wade
Ah, my favorite part of documentation mailing lists, the grammar
debates. :)
This page ...
http://fedoraproject.org/wiki/DocsProject/StyleGuide/GeneralGuidelines
... provides guidelines on using active, passive, and a commanding
voice. I'm personally not in full agreement with the recommendations,
and wanted to discuss this here, see what consensus we can reach.
In the "use active voice" camp, we generally avoid passive voice like
the plague. A hallmark of the passive voice is the word 'will', as in,
"Click OK and then the page will change to blue." Compare that to,
"Click OK and the page changes to blue." The second is more
authoritative and assuring, and provides a context-in-time. By that I
mean, it assumes the reader is following the directions in real time, in
which case, the screen is not going to eventually change to blue, it is
going to do it immediately in response to clicking OK.
Once you accept that, you quickly find that you never need the passive
voice. Even to avoid awkward sentence structure. If you want to say
that something "will happen", it either "is going to happen" or "might
happen."
Commanding voice seems to be about a more strongly worded version of
active voice. I don't see a need for it, other than as part of
admonitions. That is, we permit/suggest people are more commanding in
admonitions.
But the commanding voice examples such as, "You will click the OK
button," actually is more confusing than commanding. It sounds like a
prediction of the future. What happens if the user does not click OK?
The command is now false -- the user in the future ('will do') did not
in fact do the action. Does not compute! Circuits melting! Thus, I
find the commanding voice to be self-contradictory and self-confusing.
My thinking is to clarify the voice section thus:
1. Active voice == good
1.1 Examples of active voice
2. Passive voice == bad
2.1 Examples of passive voice
2.1.1 How to use a global search for the word 'will' to eliminate 80%
of your passive voice usage
Opinions? :)
- Karsten
--
Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project
Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject
quaid.108.redhat.com | gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
17 years, 8 months
Wiki Docs/Beats opened for changes for Web-only release notes
by Karsten Wade
You may continue to edit the Wiki at:
http://fedoraproject.org/wiki/Docs/Beats
Next Monday we are going to take another snapshot to output to XML[1]
and make available as a Web-only release notes to coincide with the
test2 release.
This test release notes is the last one that you can afford to leave
your project's content empty. If you do not have content in place for
test3, your content does not gain the community vetting before FC6
release. So, please come follow the open content methodology.
- Karsten
[1] We used a Wiki running the new code from the Summer of Code project
that has already greatly improved the XML output capabilities of Moin
Moin. When this SoC project is completed, it is going to be very, very
easy to use the Wiki as a drafting and authoring tool, then output to
XML/XHTML for DocBook and the Plone CMS.
--
Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project
Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject
quaid.108.redhat.com | gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
17 years, 8 months
update: FC6test2 release notes PO files
by Karsten Wade
We are working on the XML conversion with new tools right now. Our
current estimate is another 1.5 hours of work, which would make the PO
files available in CVS about 2 hours late.
I'll send another update when we know more.
- Karsten
--
Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project
Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject
quaid.108.redhat.com | gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
17 years, 8 months
FWN Column
by Paul W. Frields
NOTE: Followup set to fedora-marketing-list(a)redhat.com
Fedora Weekly News, in association with the Fedora Documentation
Project, is soon to start a new regular column devoted to giving answers
to common user problems. The result would be similar to "Ask Shadowman"
in Red Hat Magazine -- somewhat like a weekly FAQ, with the significant
difference being that it's completely Fedora-centric, and we have the
ability to be a bit more current through dipping into the input stream
in real time.
What do I mean by that last bit? Well, the questions are to be provided
by the community, and answers provided by knowledgeable experts in the
subject matter of each question. Questions could be submitted by users
directly. That's not very different at all -- but here's the twist:
Thomas Chung and I are hoping Ambassadors and other Marketing folks will
cull them from topics coming up currently in the Fedora Forum and on IRC
#fedora. You can then post new questions on the wiki in a queue page to
be addressed in the next week's column:
http://fedoraproject.org/wiki/WeeklyQuestions
Answers would give step-by-step solutions when possible, with short
explanations for new users. We will probably handle somewhere between
three and five questions per issue, but if we find the queue is stacking
or lacking, we will change those numbers as necessary.
Why do this? Primarily to cut down on user frustration and FUD caused
by wrong answers. When inexperienced users help other inexperienced
users, they sometimes proffer solutions which are less than optimal.
(The most common example that comes to mind is "disable SELinux," but
there are many others.) While we all appreciate the helpful spirit of
our community members, we also want to help everyone Do The Right Thing
when possible, especially if it means better education and security.
Many of the folks with the most knowledge don't spend a lot of time on
IRC #fedora or the Fedora Forums, so this is a way the community can
benefit from their expertise while requiring very little of their time.
This initiative also gives the FDP a way of judging where more
documentation is needed. We have few hands and many goals, but by
leveraging the popularity of FWN we may get some clues where best to
allocate those resources. We've got several Fedora luminaries lined up
to contribute answers to the column, so we expect this will be a great
new way to provide some community outreach.
Thomas and I will be keeping a close eye on the questions and answers
and using them to steer this initiative. If you are an experienced
Fedoran with good communication skills who would like to participate,
please put your name on the list of answer providers:
http://fedoraproject.org/wiki/WeeklyQuestions/SolversList
More to come...
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Project Board: http://www.fedoraproject.org/wiki/Board
Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
17 years, 8 months
String "Revision History" untranslatable
by Dimitris Glezos
Hi.
I noticed that the string "Revision History" remains untranslated in the
front page of the TQSD. It seems hardcoded in the xsl files.
$ find . | xargs grep -o 'Revision History'
./docs-common/xsl/main-html.xsl:Revision History
./translation-quick-start-guide/translation-quick-start-el/index.html:Revision
History
$ grep 'Revision History' docs-common/xsl/main-html.xsl
<a href="{concat('rv-',$id,$html.ext)}">Revision History</a>
-Dim
--
Dimitris Glezos
Jabber ID: glezos(a)jabber.org, PGP: 0xA5A04C3B
http://dimitris.glezos.com/
"He who gives up functionality for ease of use
loses both and deserves neither." (Anonymous)
--
17 years, 8 months
status on CVS access
by Karsten Wade
FDP is moving to a sponsored CVS access model, very similar to what
Fedora Extras is doing.
http://fedoraproject.org/wiki/DocsProject/CVSAccess [1]
The main reason is because we are moving away from CVS as being the
primary way to contribute and edit documentation. Aside from the Wiki,
we are close to putting up a full CMS on fedoraproject.org, and most
documentation workflow (write, edit, publish) is going to be handled
directly there.
CVS continues to be important for translation and full-length documents
that authors prefer to work directly in XML.
The Fedora Infrastructure team is working on migrating Fedora
Translation CVS and the CGI that handles the translators' workflow. In
the meantime, we'll continue to add individual translators. These
translators need to follow the same sponsorship model, ideally with a
sponsor being a fellow translator from their language.
Cheers - Karsten
[1] Thanks to Hugo Cisneros for his draft of this document and helping
to drive the sponsorship model for FDP :)
--
Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project
Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject
quaid.108.redhat.com | gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
17 years, 8 months
Content depth/breadth (was: Update of "Docs/Drafts/DesktopUserGuide/Multimedia" by CodyDeHaan])
by Karsten Wade
> The following page has been changed by CodyDeHaan:
> http://fedoraproject.org/wiki/Docs/Drafts/DesktopUserGuide/Multimedia
>
> The comment on the change is:
> Created. Writers, take a look and give input!
>
> New page:
> = Playing Multimedia (Music & Video) =
>
> Fedora Core 5 includes tools for viewing video and listening to audio.
>
> 'WRITERS:' What do we do here? Multimedia already exists in the Wiki...
I saw your comment in IRC as well, and I think you are referring to the
existing content at Docs/Beats/Multimedia, right?
The way to think about what is needed is to focus on the purpose of the
document. Some of the same material may be covered, but the method is
going to be different.
The release notes, for example, are a compilation of interesting,
useful, or crucial facts about a version/release. If your objective was
to bake a loaf of bread, the release notes would tell you things such
as:
* Is the supplied flour white, wheat, or a blend? Is it all purpose or
does it need additional gluten?
* Where do you get the water for activating the yeast?
The Desktop User Guide would instead be focused on answering the
questions:
* The steps for turning flour, water, yeast, and salt into bread.
* How or why different kinds of ovens affect the baking.
* How to modify the recipe if you have a different type of flour.
/me quickly finishes and sends, after letting it sit on his desktop for
a few days
- Karsten
--
Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project
Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject
quaid.108.redhat.com | gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
17 years, 8 months
about-fedora.xml
by Nikos Charonitakis
Hi
i checked out release-notes from cvs and i finally found that "about
fedora" menu entry resides in there.
So there are two files: about-fedora.xml and about-fedora.menu
Is these files covered by the usual translation procedure covered by
Translation Quick Start Guide?
I think no.
So in which way translators can localize this document and add the
appropriate localized menu entry?
Nikos
17 years, 8 months