A Three-pronged Approach to Fedora Documents

Sat Nov 18 17:39:15 UTC 2006

On Fri, 2006-11-17 at 00:18 +0300, John Babich wrote:
> Karsten, Paul and Fellow Team Members:

John, this is a good write-up that reflects mostly-accurately the
grown-to situation we are in.  That is, we have organically grown into
"what works" as much as we have planned it carefully.

Feel free to update the DocsProject pages in the Wiki to reflect this
approach, where it fails to make that clear.  Because of the organic
growth, we haven't always gone back to clean up the various leftover
processes and half-completed ideas.  Still, seeing this clarity from you
gives me hope that it can be equally clear for others. :)

Just a few additions/corrections/observations:

> Now more than ever, the Fedora Project  has captured the public's
> attention.  Now is the time to improve the "public face" of Fedora.

Agreed.  In fact, I think there is some sentiment that Fedora can begin
to do more self-promotion.  To be honest, I think the Fedora Project has
been afraid of users who are new to Linux.  That is, the fear is not
amongst the ground folks who solve problems daily on fedora-list,
#fedora, fedoraforum.org, etc.  I mean the project leadership and
majority of technical achievers.

I've long maintained that Fedora is both what we want it to be and what
it becomes by itself.  This is one reason that the FDP focuses on users
of all levels, even where the overall project does not advertise itself
as "for the beginner".

Honestly, I don't think the technical situation is going to change.
Fedora is always going to have more leading-edge technology and
associated rough user experience.  That just makes our jobs here that
much more important.

While the solution to document something instead of make it work better
without documentation is not my favorite solution, I want to get to a
point where highly technical contributors in Fedora are using good
documentation as a way to mitigate the challenges of being so
leading-edge.

> Forgive me in advance for the length of this correspondence. I hope
> you find it worthwhile.

Personally, it makes me proud of our work to have a newer someone feed
the situation back so accurately.  

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

Eclipse may also have a plug-in for working offline.  If it doesn't, we
should get someone to write one.  The purpose is to increase the
documentation we get from Fedora developers.

There are also a number of ways that content comes into FDP that you
didn't cover here.  These are discussed here:

http://fedoraproject.org/wiki/DocsProject/ReleaseNotes/Process#submitting

Note number 4.  There are also new ways that RHEL developers can make
commits to CVS and have them update bugzilla reports, etc.  That is a
process and toolchain we need to learn more about and find out how to
make it fit into the release notes process.

The idea is that we can take in all manner of content suggestions, and
some goes to release notes, others to installation guide, admin guide,
desktop guide, etc.

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

Guaranteed improvements in maintenance. :)

Our current publishing situation for anything that is not the Wiki is
quite daunting.  Plone as a CMS provides us with workflow.  This means a
writer can submit, and editor can edit (push back for change acceptance,
forward for publish), and a publisher can publish.  We can divide those
roles amongst people who may have different roles in different
documents.  All is managed through a personal queue via the Web app.

Also, by being in the Python way of things, we can write some tools to
glue stuff together.  I'll address this below under your concerns about
this three-pronged approach, and will show how we mitigate or remove the
multi-tool concerns.

> 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

It is also usable as a transition state that content can automatically
move through.

I'll note that while people are tackling the real challenges of writing
a book 100% in a Wiki, I remain quite skeptical.  The longest book I've
written is the Red Hat SELinux Guide, which is about 100+ pages in PDF,
and there is *no way* I could have accomplished the quality and level of
detail if I had to edit in a Wiki.  Even if we had found a way to not
have to edit via a Web browser.

The reason is that a Wiki is designed for doing things easily, but in
doing so it has to compress out tools that you need for a real book.

For example, in DocBook XML, you can put a construct like this anywhere
in the content :

<indexterm>
  <primary>Customizing</primary>
  <secondary>Desktop background</secondary>
</indexterm>
<indexterm>
  <primary>Desktop wallpaper</primary>
  <see>Customizing</see>
</indexterm>

Believe me that when you learn to do this with Emacs, it is really,
really easy (several keystrokes to put in the skeleton, fill in the
terms, move on).

The toolchain then makes an index from the book during each build.  The
index automatically links back (in HTML output) or provides page numbers
(in PDF).  Something was incorrect?  Fix in XML, move the term around,
etc., rebuild, and the index is fixed to match.

So, there are literally hundreds of advantages of using a full-featured
book writing tool.  And yes, that complexity comes with the price of a
steeper learning curve.

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

With a Python programmer and a few weeks of time, below is what we
intend to accomplish.  This could be done at anytime, but we have to
wait for Plone to be updated to do a full roll-out.

1. Write and edit in the Wiki.  The Wiki either works directly on XML in
CVS or on regular Wiki pages.  Some pages stay where they are forever
(project pages, e.g. wiki/SELinux, wiki/Packaging), and some are
pre-drafts (Docs/Drafts, Docs/Beats).

2. When ready, select "Publish in CMS as draft" from the 'More Actions:'
dropdown menu on the right.
  - If the content is XML in CVS already, the "Publish..." triggers off
a build of the document into XHTML and the publication into Plone under
the user's ID as a contribution at the beginning of the workflow.
  - If the content is Wiki, it is first converted to XML, wrapped in the
toolchain, then built to XHTML and published into Plone at the beginning
of the workflow

3. The assigned editor for the document receives notice of a (new)
draft.  They read and either send back to the writer with specific items
to fix, or push on to publish.

4. When published in Plone, it is put in the proper taxonomy location
and has all the slick look we can give it.

The same holds true for translation.  We can add a "Submit for
translation" that follows a similar path.  However, this button might be
in the Plone workflow, and a publishing editor uses it after content is
ready.

> 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

Ideally, a writer can choose on editor (Emacs, Vi, Gedit, Jedit, OO.org,
Wiki, etc.) and a method to commit work (CVS client or via Wiki), and
they are done.  But we have work ahead of us to get there.

> 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

Our major communication challenges is with the Translation project, and
secondary with 80% of the Fedora developers.  Within the FDP, we have
traditionally done pretty well.

Translation communication will improve when we can get CVS moved and
their tools included into fedoraproject.org.

Developer communication is just something we work on continuously.

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

There are other benefits and we should be mindful of ways to reward
people in the FDP (writers/editors/translators or w/e/t).

* Highlight contributors (name as author, translator)
* Help people to grow their skills and related interests
  - I wrote about how this can positively affect career goals here:
    http://iquaid.livejournal.com/13095.html
* Have Fedora Project bring w/e/t in for FUDCon events
* Connect Fedora Ambassadors with w/e/t to present at FLOSS events
* Get some of our content published as a real book
* Thank you gifts
* Other tangible items
* ???

> 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?])

4. Cross-stream collaboration, where we work with other documentation
teams from other projects (distros, etc.) to create or contribute to
documentation commons.

For example, fixing up man/info pages.

> To quote Dennis Miller, "This is my opinion - I could be wrong" :-)

And he so often is. :)

- Karsten
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20061118/44183c20/attachment.sig>