A Three-pronged Approach to Fedora Documents

[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>