A Three-pronged Approach to Fedora Documents
by John Babich
Karsten, Paul and Fellow Team Members:
INTERESTING TIMES
I have been digesting the amazing news over the past month, as I'm
sure you all have.
GNU/Linux distributions, including Red Hat and the Fedora Project,
have been under intense scrutiny and discussion by IT pundits and
business analysts.
By coincidence, the Fedora Summit has just ended. My impression is
that it was a successful series of meetings. There were frank
discussions of our failings, and decisive steps taken to improve the
overall quality of Fedora.
What has this to do with the Fedora Documentation Project? Did I post
to the wrong mailing list? No, I didn't. It has everything to do with
our small band of intrepid volunteers, of whom I am proud to be
counted among its members.
Now more than ever, the Fedora Project has captured the public's
attention. Now is the time to improve the "public face" of Fedora.
In my humble opinion, our website, federaproject.org, is Fedora's
primary public face. (This is not to downplay the importance of
one-to-one contacts, Fedora Ambassadors and the other organized Fedora
activities).
I joined the Fedora Websites Project within the past few days. The
Fedora website is the medium by which we publish our hard work, the
guides we produce for consumption
by our Fedora Core users, and the documents needed to effectively run
the Fedora Project.
>From what I have been reading on the mailing lists and the Fedora
Summit discussions, from my public exchanges and private
correspondence with Fedora Doc team members,
I am encouraged and inspired to get more involved.
Forgive me in advance for the length of this correspondence. I hope
you find it worthwhile.
THE WAY FORWARD
Here are some ideas I find encouraging (I take full responsibility for
any misinterpretations).
These are also very much open for discussion and debate.
1. MoinMoin Wiki - to jointly revise documents
Currently, we are taking this approach with the "Software Management
Guide". Once we're happy with the results, we can then turn guides
like this into more permanent forms like DocBook XML. I am looking
into ways to use Gedit and the new Plugins feature to speed up the
process. The "Tag Lines" plugin looks very promising. This keeps the
barrier to entry very low.
ADVANTAGE: Ease-of-use, low barrier to entry.
2. Plone Content Management System (CMS) - for a more polished look
We can use the Plone application for static pages and a more polished
look. Of course, we need to decide what exactly is "static" versus
"dynamic". I propose that the "index.html" or equivalent be static,
with dynamic updating going on in Drafts. Once a document is
finalized, then we can make it "static" in Plone and jointly edit the
new version in MoinMoin.
ADVANTAGE: Polished presentation and possible improvement in maintenance.
3. Emacs and DocBook XML - for greater flexibility
We can use Emacs and DocBook XML to publish our efforts in any desired
format: web pages, PDFs, Postscript, etc. The advantage of this is the
"write once, use often" approach, which is a primary tenet of modular
programming and the basis of FLOSS. These documents are also the base
for the many translations which are produced by our Translation team
members.
ADVANTAGE: Modular efficiencies, "reuse of code", standard "code" base
There are definite disadvantages to this three-pronged approach. It
would be great if we could do everything with one tool - maybe someday
soon we will. For now, we can enjoy the advantages this approach
offers. Now here are the disadvantages, which I would rather call
challenges.
THE CHALLENGES
1. Complexity.
Three tools are harder to use than one tool. Most of us know one tool
really well, some of us know two tools pretty well, and a few know all
the tools (of whom we stand in awe). For instance, I've got a pretty
good handle on MoinMoin, a desire to learn Plone, and a basic grasp of
Emacs and DocBook XML. There is also the issue of conversion from one
format to the other.
This is why the team approach (the bazaar) is so powerful. As a
community, we are stronger than as individuals. We can pool our talent
and produce a whole greater than the sum of its parts. We also have
powerful FLOSS tools.
SOLUTION: Teamwork, teamwork, teamwork and tools, tools, tools
2. Coordination of Effort.
This is always a challenge. Many times "we have a failure to
communicate". The good news is we have great tools at our disposal:
wikis, email, IRC channels, etc. People are making good money
promoting "collaboration". We have the tools we need already at hand -
we just have to make use of them. New tools are emerging like VoIP.
SOLUTION: Use our great FLOSS communication tools creatively
3. Multilingual Teams.
This is a challenge that arises from our success. GNU/linux is a truly
global phenomenon. Just look at all the languages our Fedora
Translation team supports. I can tell you from personal experience
that this challenge is overcome everyday by international and
multinational companies.
My current employer (who, for the record, is not officially sponsoring
my strictly volunteer efforts) employs over 40 nationalities from many
different cultures and languages. Somehow we manage to execute large
engineering projects all over the world, and execute them well.
I especially love English in all of its shades and subleties. My
personal challenge is to consider my audience first. I try to speak
and write in clear standard English. It's amazing how many local
dialects of English exist. Our challenge is to write and speak English
free of idioms and local color - and still have impact ("pack a
punch"). We should do this out of respect for our Fedora users for
whom English is a second language.
SOLUTION: Use standard English and be sensitive to difference in
language and culture.
4. Dedication.
This is a personal decision - how to invest your limited time and
resources. Again, the solution is to prioritize your life. How
important are the goals and objectives of the Fedora Project to you
personally. How has the recent news affected you? Has it made you glad
or mad, discouraged or more determined?
SOLUTION: Up to you.
FUTURE TOPICS
1, Upstream contribution to other documentation projects (for example, GNOME).
2. Improvements to document conversion tools.
3. Better communication (VoIP, online presence tools [MugShot?])
To quote Dennis Miller, "This is my opinion - I could be wrong" :-)
John Babich
<Brainflush completed>
17 years, 5 months
FDSCo semi-meeting minutes
by Karsten Wade
Due to sudden familiness, I wasn't able to attend the meeting yesterday.
Some stuff was discussed, I dragged it from the IRC log, and here it is:
* New Fedora Infrastructure (FI) members have been working on putting
squid proxies in front of Moin Moin. However, taking advantage of the
proxies requires an update to 1.5+ or another patch.
* They are also putting together a test instance of the Wiki in the
Phoenix datacenter. This lets us test upgrades and see what problems we
are going to have with migrating content, etc.
* Paul requested that the governor that limits how hard pages can be hit
be removed either permanently or during release cycles. We need this so
we can get the relnotes as XML out of Docs/Beats/ using a script. Since
only CLA-having people can edit the Wiki, there is probably no need for
the governor. Mike McGrath/FI will look into this.
* Not covered in this meeting, but worth noting:
- Python versioning on fpserv.fedoraproject.org is preventing us from
rolling out the Plone instance. We are waiting for upgrading to RHEL
5/CentOS 5 to get the new Python version. This pushes the Plone roll
out back to at least January 2007.
- 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, 5 months
Self-introduction: Dave Wolinski
by David Wolinski
Hi,
My name is Dave Wolinski. I live in the Boston, MA, area and do
research/development work for MIT Lincoln Laboratory.
I've been a Red Hat enthusiast for many years and use Fedora both at
work and home. I've been consistently impressed with the quality of
this free product and would like to give something back to the Fedora
community. Since I'm basically a hack programmer, it seems that
documentation would be a good way to achieve this goal (and hopefully
learn something in the process). Like exercising or other painful but
rewarding activities, I enjoy having written (i.e. past tense) something
well.
In my limited spare time I hope to contribute to the very finite (though
interesting) topic of building a customized kernel (thanks to Sam F-W
for steering me this way).
Cheers,
Dave
----------
pub 1024D/6B214FAA 2005-07-23
Key fingerprint = A994 677C 44FB EF66 84F9
EF7B 8C8B 4FFC 6B21 4FAA
uid David S. Wolinski <dwolinski(a)ll.mit.edu>
sub 2048g/A2CFCCD9 2005-07-23
17 years, 5 months
A Modest Proposal for a New Guide
by John Babich
Fedora Docs Team Members:
One area which appears to be overlooked is the installation and
updating of software by the novice user. Various sections exist (such
as the excellent one on yum - see http://fedoraproject.org/wiki/Tools/yum),
but there is no "gentle introduction" for the person new to Fedora Core.
According to the Documentation Summary section of the Desktop User Guide:
<quote>
*Assumptions:* The reader has a standard Desktop class installation of
Fedora.
The reader has a user account with the default settings.The reader does *not
*
have access to the *root* password.
*Related Documents*: The
AdministrationGuide<http://fedoraproject.org/wiki/Docs/Drafts/AdministrationGuide>documents
tasks that require
*root* access. The
GettingStartedGuide<http://fedoraproject.org/wiki/Docs/Drafts/GettingStartedGuide>is
a general introduction to using Fedora.
Each desktop application has integrated Help, so the scope of this document
may need to be considered carefully.
<end-quote>
I agree with the DUG assumption not requiring the novice user to have access
to the root password. This keeps the DUG focused on the basics.
However, a quick review of the Administration Guide reveals no section on
the
installation and updating of packages.
The Getting Started Guide has the following section:
<quote>
Cool Things To Do with Fedora
Everything above gives users equivalents to a standard Windows desktop that
they have seen before. What cool things can new users try with a Fedora
system that take them further ?
-
LinPhone <http://fedoraproject.org/wiki/LinPhone> - demonstrates
installing from Extras, and free phone calls. Requires: headset.
-
GnuCash <http://fedoraproject.org/wiki/GnuCash> - installs from Core,
home finance software isn't cool, but is important.
<end-quote>
However, the links for installing LinPhone and GnuCash don't link to
existing pages.
A MODEST PROPOSAL
Therefore, I propose a separate Installing and Updating Software Guide aimed
at the beginning Fedora Core user. I volunteer to write and edit the guide
and
welcome any and all contributions and suggestions. (That includes a better
name for this guide). We would start from the Fedora Core 6 release.
This assumes, of course, that I get the "go ahead" from the Powers That Be.
PROPOSED OUTLINE FOR THE IAUSG
These would be the assumptions for the Installing and Updating Software
Guide:
*Assumptions:* The reader has a standard Desktop class installation of
Fedora.
The reader has a user account with the default settings.The reader **hasaccess
to the *root* password. The reader has access to the internet (preferably
broadband).
The reader does not have a degree in Computer Science.
We need to give some background information and provide concepts and details
as required.
As suggested by the Getting Started Guide, we can demonstrate different
classes of
installs, such as from the Core and Extras repositories.
We should also demonstrate different methods of installing packages,
going from the simplest to the more complex.
1. Install a package like xmms using Pirut. (Perhaps xmms with fluendo?)
2. Install Yumex via Pirut, and then install (perhaps a game) via yumex.
3. Use rpm from the CLI to view a list installed packages (no root password
required).
4. Use rpm to install a locally available package (root password required).
5. Use yum to install a package from an internet repository.
6. Use yum to provide various reports.
7. Use yum to do a group-level installation, such as a complete KDE
desktop installation.
8. More advanced topics:
a. Using smart.
b. Using apt-get.
c. Using yum at installation time via the new anaconda feature.
Likewise, we should cover the topic of updating packages in a similar
progression from the simple to the advanced.
1. Update packages using Pirut.
2. Update using Yumex.
3. Update using yum from the CLI.
4. Selectively update using yum (including/excluding packages
and disabling/enabling repositories).
5. More advanced topics:
a. Do a complete Fedora Core release upgrade (I actually have done
this successfully on a laptop with a bad CD drive and broadband
internet access.)
FURTHER READING (RELATED DOCUMENTS)
As always, we should provide pointers to good links, both inside and
outside of the Fedora Core wiki.
FLOSS AND COTS PACKAGES
Additionally, we should stick with FLOSS software and avoid packages
which violate the GPL. At the same time, we should remember that there
are legal, commercially available packages which can be covered in
general terms. Most of these commercial-off the-shelf (COTS) packages
come with detailed instructions and/or installation scripts, so this
section can be short.
This guide should follow the guidelines and policies for the Fedora
Core wiki concerning "forbidden items" (not my favorite term). See
http://fedoraproject.org/wiki/ForbiddenItems.
<http://fedoraproject.org/wiki/ForbiddenItems>
(Aside: Maybe we can come up with a less harsh-sounding phrase than
"forbidden items".)
In conclusion, ala Rod Serling's Twilight Zone, this is submitted "for your
consideration."
John Babich
17 years, 5 months
Toolset idea
by Paul W. Frields
This might be a useful mode of thinking about the Wiki/Plone+DocBook+SCM
[1] duality that does not put any burden on contributors who don't want
to learn the latter toolchain. What if Plone was set up so that:
1) The Wiki side was published automatically from a DocBook -> wiki
conversion mechanism, provided no blocking tag is in the way.
2) If someone edits the Wiki, it automatically gets an aforementioned
blocking tag that says, "Manual change here!"
3) The commit to the wiki is automatically entered into the Fedora
Bugzilla as a bug, which goes to the owner of the doc in question via
the normal route. The bug entry could be as simple as the commit
message itself.
4) Once the writer addresses the bug, the editor approves it and clears
the blocking tag from the wiki page. This might be susceptible to
automation too.
5) Next automatic publication sees the user's fix in the wiki as well as
every other place.
This workflow idea encourages not only "unskilled" contributions from
the whole community but ensures that we keep the wiki and CVS+DB in sync
as much as possible. Bugs always make it clear what needs to be done.
I found that as I watched the release notes over the entire Rawhide ->
test1 -> test2 -> test3 -> final cycle for FC6, I was able to keep up
much better with editing changes by watching my email for wiki commits.
As I addressed a page, I could clear out every email concerning that
page up to the date I last visited it for an editorial pass. Sending
wiki commits to bugs in this fashion would make (I think) a very
efficient way of syncing our material, keeping SCM + DocBook as the
canonical source while locking no one out of the contribution process.
Maybe this is not something novel, and I'm just late to the party as
usual. Thoughts?
= = =
[1] SCM = Source Code Management, whether we move to git, hg, or
something else other than CVS in the future
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Project Board: http://fedoraproject.org/wiki/Board
Fedora Docs Project: http://fedoraproject.org/wiki/DocsProject
17 years, 5 months
Re: A Modest Proposal for a New Guide
by Shayin C K
I think it is a good idea. As soon as the 'Powers-that-be' approve it,
we can have a go at it.
My own suggestions and ideas:
1. The section on Getting Started begins with how it is similar
to/different from Microsoft Windows. I think Fedora has matured to a
point where we have to get rid of this Windows fixation where we have to
point out how better or worse Linux is compared to Windows.
2. The Desktop user guide reads: "After reading this, you
_should_(emphasis mine) be able to ..." Suppose a user is not able to
all that? Is he supposed to feel bad about it?
I think our style should be more non-judgmental and without laying any
targets for the user. Let us not set any objectives for the user. Let
him get started. Let us not intimidate him.
3. The number of technical sounding words can be brought down or at
least they can be suitably hyperlinked(another technical word ;-) ). For
example(fedora Desktop guide):
-------------------------------------------------------------------------------------------------------
After reading this guide, you should:
*
Be able to login to your computer
*
Be familiar with the layout of the default Fedora Core 6 desktop
*
Be able to use Nautilus, a file and system navigator
*
Be able to use Evolution, an e-mail client
*
Be able to use Gaim, an instant messenger client
*
Be able to use Firefox, a web-browser
*
Be able to use OpenOffice, an office suite
*
Be able to customize your new Fedora Core 6 desktop
-----------------------------------------------------------------------------------------------
The technical words:
login, layout, default, desktop, file, navigator, e-mail 'client',
web-browser, office suite, customize
Let us assume that a new user who has never used any
computer(Windows/non-windows) starts using Fedora Core and we have to
manage to get him working. Why do we assume that only a technically
experienced user will be switching to Linux?
Regards
Shayin C K
17 years, 5 months
Re: FC7 through FC10 Name Proposals
by Markus McLaughlin
Hi Fedora Fans/Users/Programmers!!!
This is definitely an exciting day for us Fedora Fans/Users/Programmers!
I am downloading the MAC-PPC edition of FC6 all day today on my day off
from work. I love the name ZOD, very cool, and a nice reference to
General
Zod of Superman lore. Now here are names that I hope will be considered
for the upcoming releases. Star Trek turned 40 this year so I
propose the
name for Fedora Core 7 to be Spock. I will write to startrek.com and
trektoday.com and the Trek BBS if that is okay to be used since it
won't be
a name that can be sold. Along with the Spock name, I want to encourage
programmers who know how to create themes to create an "LCARS" theme
that looks a lot like a computer display on board the Enterprise-D as
shown
in ST-TNG complete with animated icons and/or panels.
Here are names I hope will be considered for FC8 through FC10.
Athena, a
Greek Goddess, would make an appealing name for FC8. FC9 should be
named either Brando, Kurtz, Vito, Jules, Vega, Tarantino, Starbuck,
Baltar,
Pryor, Kennedy, or Boston.
In honor of Linus Torvalds' work on the Linux kernel, Fedora Core 10
will
be known as "Hattu," which is Finnish for Hat. It will also honor my
Finnish
roots as well, half of my ancestors/family comes from Finland so I
insist
on this name as well. The other half being Irish American, my
ancestors
came from Ireland.
Please consider these names in the months to come but PLEASE use "Hattu"
for Fedora Core 10, it would be the logical thing to do....
BTW, Fedora Core needs an optional Sidebar a la Vista in both GNOME and
KDE, customizable of course. I think FC should have a really good
expanded
"Start" panel as well in future releases. Finally, some cool
animated icons
would be a nice touch in FC7...
Mark McLaughlin - marknetproductionsentrance.blogspot.com - Hudson,
MA, USA
17 years, 5 months
ANNOUNCE: docbook-lint: a tool for checking DocBook source files
by David Malcolm
[apologies for broad cross-posting]
I wanted to do a bit of checking of DocBook XML files beyond just DTD
validation, and couldn't find a tool to so this (is there one?), so I've
hacked one together (GPL license, python implementation)
In the spirit of "release early, release often", the code is in public
Subversion here:
https://testing.108.redhat.com/source/browse/testing/trunk/incubator/docb...
and the mailing list for the project is:
dev(a)testing.108.redhat.com
(see https://testing.108.redhat.com/servlets/ProjectMailingListList for
archives and subscription info)
So far all it does is verify that text inside a <computeroutput> element
has been properly line-wrapped [1], but the framework is hopefully clean
enough to be expanded to cover other checks people might want to
implement that aren't so easy to do with DTDs, for instance:
- enforcing naming policies for node ids
- spell-checking
etc - any other ideas? Patches welcome.
Hopefully this will be of use to various projects with DocBook
toolchains.
Dave Malcolm
[1] I ran into some problems where line-endings of screen dumps in my
DocBook files got garbled, and verbatim monospace rendering was looking
terrible: the tool detects this now.
17 years, 5 months
