Outage Notification - 2008-10-05 07:00 UTC
by Mike McGrath
There will be an outage starting at 2008-10-05 07:00 UTC, which will last
approximately 2 hours.
To convert UTC to your local time, take a look at
http://fedoraproject.org/wiki/Infrastructure/UTCHowto
or run:
date -d '2008-10-05 07:00 UTC'
Affected Services:
Buildsystem
CVS / Source Control
Database
DNS
Fedora Hosted
Fedora People
Fedora Talk
Mail
Mirror System
Torrent
Websites
Unaffected Services:
All
Ticket Link:
https://fedorahosted.org/fedora-infrastructure/ticket/875
Reason for Outage:
Doing our monthly updates to our systems, there's a kernel update this
time around and we'll be rebooting everything. In theory most systems
won't go down at all. But many will be down for a few minutes at a time
during our 2 hour outage window.
Contact Information:
Please join #fedora-admin in irc.freenode.net or respond to this email to
track the status of this outage.
15 years, 7 months
A New Look at How We Write Content for the Desktop User Guide
by Elizabeth Ann West
Hello All,
I am a fairly new contributor to Fedora-Docs, and a <1 year Linux user.
My background is predominantly writing, so I approach the documentation
more from a literary stand point than a heavily entrenched computer
user. If anything, I'm a good example of the type of person you are
looking to convert from proprietary software to open source.
I took a hard look at the Desktop Users Guide F9, specifically the page
giving instructions to install financial software. First, there was a
large issue with the content-- the instructions simply would not work
for a new user with Fedora 9. Second, the instructions were not clear
for a brand new user to Linux.
After finishing the content change, and major style changes to the
Financial Software page, I deconstructed the changes and differences so
others may learn from them, and contribute their own ideas and
experiences. Yes, we are writing documentation for free, but we have an
opportunity here as open source enthusiasts to use our piece of the
project at large to further the cause and acceptance of Fedora as an
operating system. These suggestions below are only for the Desktop Users
Guide, the specialized guide for new users of Fedora, presumably coming
from Windows, without Linux experience.
For discussion purposes, this is the old page:
https://fedoraproject.org/wiki/Docs/Drafts/DesktopUserGuide/Financial
This is the new and improved page:
https://fedoraproject.org/wiki/User_Guide-Financial_Software
Here are the major improvements I want to point out as potential "best
practices" for future work on the Desktop User Guide:
* The page stands completely alone for a new user.
Links and everything are great, but switching to a new operating system
is highly nerve-wracking. I have done this 3 times in the last 5 months,
including my first switch to Linux from Windows. Experienced Linux
users take so much for granted, when just something as simple as
installing software from a command line is foreign (a distant memory for
Windows users who remember DOS). Ease new users' frustrations by
providing all needed instructions in one document page or chapter that
apply to functionality, or getting something done. Certainly link to
topics that may be of interest to me for other actions, but don't leave
out information I need to accomplish what I want/need to do right now.
It's like giving landmarks when you give someone directions for the
first time, instead of letting them rely just on Mapquest, or sending
them an entire road map for the state.
* Stand alone chapters fit in more with how all users utilize help
manuals.
We're all guilty of this one. No one voluntarily reads a help manual
from cover to cover unless he or she absolutely must. New and old users
alike use an index for printed manuals to jump right to the information
needed, and electronically search is a godsend. Working to write and
offer stand alone chapters helps the users help themselves in the manner
they naturally will try first. The fewer places a user must go for
information, the more likely he or she can use the data effectively.
* White space is visually pleasing in print and electronically.
The old version crams together two sets of instructions to perform the
same task, without clearly delineating when the desired result is
accomplished in either situation. The new version sets off the simple
sentence "[Application] is now installed on your computer." with a
double line space on each side. This naturally draws the eye to the
completion of the first set of instructions, without a garish ALL CAPS
or other formatting scream. Breaking up complex instruction sets with
this practice re-focuses the reader's attention. This is vital, as it is
likely the user is hopping between windows, reading directions, and then
carrying them out. Under the old instruction set, a new user from
Windows very possibly could install with the command line, miss the
concept that terminal and Pirut are two different methods of the same
thing (after all both are new to the user), and keep following the
directions ticking that box to remove the application. Over and over
again until they decide it's just broken. The new page lets the reader
know in the introduction two installation methods are available, and
then uses white space to reinforce the distinction.
* Give Graphical User Interface(GUI) example before command line,
if possible.
The Desktop User Guide has an audience of someone with no previous Linux
experience. So, start with what is familiar, and move to the unfamiliar.
The prevalence of Windows has made mainstream computer users clickers,
clickers, clickers. Even shortcut commands are forsaken in the culture
of right-clicking. Windows has trained people to click 'Next', a
seemingly infinite numbers of times, and follow baby steps. It will
naturally occur to the new users how powerful and efficient the command
line is to Linux. Eventually, they will get to where they want to do
something beyond the scope of the Desktop User Guide and it will only
have instructions for the command line in a forum post or other
documentation. Starting out, it's enough for them to know it exists and
it will accomplish the same tasks as that clicking. Now, if the topic is
on the command line commands, there is little reason to start with GUI.
* Qualify the information the user is reading.
One of the largest differences between Windows and Linux a new user
immediately encounters is just the sheer increase in information his or
her computer is sharing. On top of the increase, the computer also
demands new decisions the user never had to make before. What do you
mean I have the option of NOT installing these other packages, the ones
you are telling me will make this package I do want work? People are
naturally intimidated by notations they do not understand, like the
numbers with decimal points under a package's name in Add/Remove
Software. With instructions, leaving out actions or messages the
computer will give confuses a new user. It starts questions that stop
the process of learning: Is this normal? Where is this in the
instructions? Why can't I find this step? Did I mess up? Going back to
the landmarks concept when you give someone road directions, I added the
messages Add/Remove Software gives while it is performing the user's
requests.
This is from my personal first experiences with Add/Remove Software, it
was s......l......o......w (I fixed it when I disabled the auto-updater,
not advice I want to share as a good habit to get into). Everything
else, Internet, chat, was moving very briskly. As soon as I quit
everything and just started Add/Remove Software it was still so
painfully slow even I gave up a few times trying to install GnuCash. If
I was reading instructions, the "Downloading repository information"
landmark would at least reassure me the application was still working,
not stuck or refreshing itself.
Some other quick notes:
* Changed icon info to "associated" as neither installation method
auto-creates desktop launcher. Didn't get into that because it
doesn't fit the "do I need it for this function" litmus test.
* Clarified confusion the first page had of Live-CD versus DVD to
plainly state DVD has both, does not install automagically, if
you do not have Internet access use the DVD, otherwise..... list
of instructions to install.
* Qualified the information that suddenly appears in the bottom
boxes when they tick the box as just extra information so they
don't think it affects the install.
* Included [y/N] step for command line so the new user isn't
hesitant about answering yes. Anytime a Windows user encounters
typing 'y' or 'n' it's not usually a good thing. Also, again
qualified all that test the Terminal spits out is just
information about the application so they don't try to keep up.
* Opted to teach Search box rather than clicking Office category
because Office category takes too long to populate, and new
users will be turned off trying to find the exact name of the
package to install from that long list when none of the icons
are different.
Limitations/Criticisms
* Have not placed in links to those "extra words and concepts"
like KDE Desktop Environment should link to the page about that.
I don't quite understand yet which are new versus old, versus
frozen in the document structure (many all look the same to me).
I need help to add that in.
* Have not taken my editor's scalpel to the wording. I know there
are a number of passive sentences, but I am too close to the
text right now to see the problems or areas for improvement. In
a few days, I can better judge nuances in wording.
* Other writers may not care for this style as it is more
involved, and fights against the elitist concept of self
discovery that is so common in the open source community.
* Other writers and Fedora doc leaders may not care for the
writing style because of the departure from the traditional, or
view it as repeating the same information over and over again.
* Many others I'm sure.....
I invite others to weigh in on this issue. I am very open to hear
criticism and realize critiquing my content is not the same as
critiquing me. :) I want to offer my strong English background to help
our group as a whole start to question when we work on documents: Who am
I writing this for? What knowledge will they already know?
Always Smiling,
Elizabeth Ann West
15 years, 7 months
L10n and Docs fallback
by Paul W. Frields
We have several problems currently brewing with using hosted git repos
of Publican-based documents with L10n's Transifex (Tx).
1. Publican uses multiple POT files instead of the single POT model.
Transifex apparently does not currently handle multiple POT files
well.
2. The current (obsolete but soon to be replaced) Damned Lies (DL)
used in L10n doesn't respond well to multiple POT files either.
3. There may also be some issues in Tx about support for the ISO
language codes used in Publican.
I've asked Dimitris Glezos to give us an idea how much work is
involved in fixing each of these factors.
Problem #1 is a high risk, and if we can't solve it quickly we have to
fall back to our original methodologies.
Problem #2 is lower risk, because DL is being obsoleted anyway, and Tx
will soon take over its duties. Plus there is the possibility of a
low-drag workaround, which I think some folks are working on now.
Problem #3 is medium-to-high risk -- again, translators need to be
able to get at the content.
I expect Dimitris, Asgeir, and other L10n leaders will respond to this
thread with some suggestions for (1) some estimate of how big these
problems really are, (2) whether they can have the higher-risk ones
repaired in the next, say, 1-2 weeks.
--
Paul W. Frields http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://redhat.com/ - - - - http://pfrields.fedorapeople.org/
irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
15 years, 7 months
New language codes?
by Paul W. Frields
If the Docs Project is able to complete a transition to Publican for
the release notes for Fedora 10, many of our language codes will
change to ISO standards. This includes moving from en_US to en-US, as
in "Release_Notes-en-US.txt".
It would probably be good if any tools used to spin or release the
distribution get updated to support both of these options. I would
suggest shifting them to use the ISO standard, en-US, first and the
try falling back to en_US. That way, if we fail utterly and have to
drop back to the old way of doing business, the results will still
land properly.
--
Paul W. Frields http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://redhat.com/ - - - - http://pfrields.fedorapeople.org/
irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
15 years, 7 months
Re: version comparison guidance (was Re: self introduction and rel notes advice)
by Dale Bewley
----- "Karsten 'quaid' Wade" <kwade(a)redhat.com> wrote:
> In general, the marketing approach is to talk about GA to GA. For
> documentation, I could see arguments either way.
>
> Dale - great question! Let's hash it out on list, set the guidance,
> and
> then you'll know.
It seems to me that release notes are strong marketing pieces, and are inherently documentation. For prudent people the release notes are often the the first thing they consult before upgrading, or taking the time to evaluate software through installation.
Describing the differences using the previous release notes gives one an apples to apples comparison. Also, assume F9 released with v1.0 of a pkg. Through updates it is now at v1.9. If F10 releases with v1.9, or even v2.0. Do you not describe all those enhancements between .0 and .9? I'd think those features would be worth bragging about in the rel notes.
That's basically how I came to the question. F9 has seen a few upgrades of libvirt with many feature enhancements from v0.4.2 up to 0.4.6 currently. I think describing the delta from 0.4.2 to the F10 version (0.4.6? 0.4.7?) is the only useful way to do it.
--
Dale Bewley - Unix Administrator - Shields Library - UC Davis
GPG: 0xB098A0F3 0D5A 9AEB 43F4 F84C 7EFD 1753 064D 2583 B098 A0F3
15 years, 7 months
self introduction and rel notes advice
by Dale Bewley
Howdy.
I guess I'm supposed to talk about me a little bit first.
I switched from Slackware on a pile of floppies to RH 3.3 back in the day.
I contributed a couple of RPMs to redhat-contribs. I ran RH through 9, and
I've been using Fedora since Core 1. I'm versed in system administration,
networking, and programming (scripting mostly). I run a public mirror. blah de blah...
Anyway, I started the FWN Virtualization Beat[1], and have been doing it
for a few weeks now. Jason Taylor saw it, and asked if I wouldn't mind working
on the Fedora 10 Virtualization Release Notes[2]. I would like to do that.
I have started to gather up info, and scratch together a very rough draft
on my user page.[3] I'll move it to the Beat page soon; when it's less scratchy.
A couple of questions.
When describing new features of a release, should one describe the
improvements between the feature as it existed at F9 release time or as it
exists in the most recent F9 updates? I assume the former.
I'm dense. Can someone explain the schedule[4] to me? Apparently the beats
were recently combined on 9/22. Is the next deadline 10/2 (Translation
Freeze)? And the final deadline appears to be 10/29?
Thanks!
[1] https://fedoraproject.org/wiki/FWN/Beats/Virtualization
[2] https://fedoraproject.org/wiki/Docs/Beats/Virtualization
[3] https://fedoraproject.org/wiki/DaleBewley#Virtualization_Release_Notes
[4] https://fedoraproject.org/wiki/DocsProject/Schedule
--
Dale Bewley - Unix Administrator - Shields Library - UC Davis
GPG: 0xB098A0F3 0D5A 9AEB 43F4 F84C 7EFD 1753 064D 2583 B098 A0F3
15 years, 7 months
F10 Beta release
by Paul W. Frields
Great job with the release this morning, guys. I know there were some
gremlins in a torrent or two, but overall very painless and you guys
made it look easy (as always). Hurrah, another milestone on the path
to Cambridge!
If anyone has any issues, we could plant them on a page for the next
release day planning group call.
--
Paul W. Frields http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://redhat.com/ - - - - http://pfrields.fedorapeople.org/
irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
15 years, 7 months
Re: F10 Documentation
by Asgeir Frimannsson
----- "Asgeir Frimannsson" <asgeirf(a)gmail.com> wrote:
> On Tue, Sep 30, 2008 at 3:13 AM, Dimitris Glezos <dimitris(a)glezos.com>
> wrote:
> > 2008/9/29 Paul W. Frields <stickster(a)gmail.com>:
> >> On Mon, Sep 29, 2008 at 05:19:14PM +0530, Ankitkumar Rameshchandra
> Patel wrote:
> >>> Dimitris Glezos wrote:
> >>>> 2008/9/26 Paul W. Frields <stickster(a)gmail.com>:
> >>>>
> >>>>> On Fri, Sep 26, 2008 at 12:08:31PM +0300, Dimitris Glezos
> wrote:
> >>>>>
> >>>>>> We'll need the usual steps followed to add these modules to
> transifex:
> >>>>>>
> >>>>>> http://fedoraproject.org/wiki/L10N/FAQ#add-transifex
> >>>>>>
> >>>>>> The most important ones are having 'transif' added to the
> respective
> >>>>>> account system groups and notifying us with which <VCS root,
> module,
> >>>>>> branch> to use. One bug report for all moved Docs would be
> sufficient,
> >>>>>> and we can re-open it when a new module has been moved.
> >>>>>>
> >>>> All 7 docs projects have been registered and enabled [1] in
> Transifex.
> >>>>
> >>>> https://translate.fedoraproject.org/submit/module/
> >>>>
> >>>
> >>> Can we get all 7 docs projects enabled in DL as well?
> >>
> >> I think Dimitris mentioned earlier that Damned Lies won't support
> >> Publican's multiple POT files. It would be great if Red Hat
> I18n/L10n
> >> would collaborate with the community to help pave the way for
> >> statistics reporting for these repos. I don't know whether that
> means
> >> fixing part of DL, or simply accelerating the rate at which
> >> statistical support in Tx is written. I know Dimitris, Asgeir,
> and
> >> any of the other Tx developers would be thrilled to have some
> >> assistance with this.
> >
> > Patches are welcome with champagnes and fireworks, as always. :D
> >
> >> In the meantime, Dimitris also suggested a workaround using some
> sort
> >> of simple Python script. I doubt that's been written yet, maybe
> >> someone can help there?
> >
> > Here's a sample skeleton for such a script/scenario, for anyone
> who'd
> > like to actually code it.
> >
> > -----------------------
> > == Get the source ==
> >
> > First time:
> > $ project-list = ['about', 'release-notes']
> > $ for p in project-list:
> > git clone git://git.fedoraproject.org/git/{p}.git
> >
> > Later, to pull new changes:
> > $ for p in project-list:
> > git fetch && ...
> >
> > == Calculate statistics ==
> > $ wget http://.../fedora-docs-l10n-script.py
> > $ python fedora-docs-l10n-script.py pt_BR
> > pt_BR statistics:
> > about: 80% (115T, 40F, 10U)
> > release-notes: 80% (115T, 40F, 10U)
> > -----------------------
>
> If I remember correctly, publican actually has a 'genearate
> translation statistics' make target that can even generate HTML.
>
> Would it be ok If I set up a cron job that:
> 1) Puts translation statistics on a public web page (to make it
> simple, e.g. my fedorapeople web space)
> 2) Sends updated statistics to fedora-trans-list daily, or even after
> each 'submission' depending on how much we want to spam that list...
>
> In addition, we could add a link to this stats through the front page
> of translate.fedoraproject.org
>
> Comments on this workflow is welcome, but I'll try to make sure we at
> least have some statistics for our documentation SOON.
>
> I guess the fedora infrastructure is in 'freeze' mode, so I'm not
> sure
> how easy it would be to make the script run inside the
> infrastructure... But the main concern now is giving translators some
> statistics :)
>
> But first for some breakfast...
Could anyone review the attached script for converting release-notes to a publican-friendly PO structure?
Figured I'd learn ABC in bash scripting while I was at it...
I could send out a git patch, but it makes it a bit hard to see what I was doing...
cheers,
asgeir
15 years, 7 months