The Fedora Project is using this approach to produce the release notes and other documents in a collaborative manner. See [[DocsProject/ReleaseNotes/Process| The Release Notes Process]] . We have publicly been complimented on the quality of this work.

−

−

The Fedora Project is using this approach to produce the release notes. See [[DocsProject/ReleaseNotes/Process| The Release Notes Process]] . We have publicly been complimented on the quality of this work.

−

−

Currently, we are experimenting with updating the "Software Management Guide" in a similar manner. Once the wiki entries are finalized, the guides are converted into Doc<code></code>Book XML.

We can use the Plone CMS (Content Management System) application for static pages and a more polished look. Of course, we need to decide what exactly is "static" versus "dynamic". It has been proposed that the "index.html" or equivalent be static, with dynamic updating going on in Drafts. Once a document is finalized, it can be "static" in Plone and the team can jointly edit the new version in MoinMoin.

DISADVANTAGES: Learning curve in Plone, which includes Zope and Subversion.

==== DocBook XML - greater flexibility ====

==== DocBook XML - greater flexibility ====

Line 57:

Line 44:

DISADVANTAGES: Learning curve in Doc<code></code>Book and XML (similar to HTML).

DISADVANTAGES: Learning curve in Doc<code></code>Book and XML (similar to HTML).

−

=== Challenges Resulting from This Approach ===

+

==== Publican - greater versatility ====

−

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 obstacles, which are best seen as challenges.

+

Publican is the open-source tool developed originally by Red Hat and used in-house for its documentation since approximately 2006. This is a great tool for taking Doc<code></code>Book XML and publishing it in HTML, plain Unicode text and PDF.

+

+

ADVANTAGES: Open-source tool which handles conversion to three of the most common types of output with built-in support for branding.

+

+

DISADVANTAGES: Some learning curve.

==== Complexity - too many tools and techniques ====

==== Complexity - too many tools and techniques ====

Line 88:

Line 79:

{|

{|

|-

|-

−

| [[DocsProject/WorkFlowIdeas/AdvancingtheProject| Next Page - Advancing the Project and Community]]

+

| [[Improving_the_Docs_Project_workflow_-_Advancing_the_Project_and_Community| Next Page - Advancing the Project and Community]]

|}

|}

+

+

[[Category:Docs_Project_process]]

+

[[Category:Improving_the_Docs_Project_workflow]]

Latest revision as of 21:54, 22 May 2009

Old pageThis page has been marked as "old", and likely contains content that is irrelevant or incorrect. If you can, please update this page. This page will be deleted if action is not taken.

Introduction

This is a collection of ideas currently being discussed to improve the publication of official Fedora content. These ideas have been raised by various Fedora Documentation Project team members. They are collected here so that the FDP team can review and further refine the workflow process.

Think outside the box New ideas, suggestions, tools and techniques are welcome.

The Current Setup

Media Wiki - online editing

The Fedora Project is using this approach to produce the release notes and other documents in a collaborative manner. See The Release Notes Process . We have publicly been complimented on the quality of this work.

DocBook XML - greater flexibility

A contributor can use his or her favorite editor and DocBook XML to publish material in any desired format: web pages, PDFs, Postscript, etc. While some contributors may prefer Emacs, others are free to choose another editor. The advantage of this is the "write once, use often" approach, which is a primary tenet of modular programming and intrinsic to FLOSS. These documents are also the base for the many translations which are produced by our Translation team members.

Publican - greater versatility

Publican is the open-source tool developed originally by Red Hat and used in-house for its documentation since approximately 2006. This is a great tool for taking DocBook XML and publishing it in HTML, plain Unicode text and PDF.

ADVANTAGES: Open-source tool which handles conversion to three of the most common types of output with built-in support for branding.

DISADVANTAGES: Some learning curve.

Complexity - too many tools and techniques

Multiple 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. 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 expertise and produce a whole greater than the sum of its parts. We also have powerful FLOSS tools from which to draw.

SOLUTION: Teamwork, teamwork, teamwork and tools, tools, tools

Coordination of Effort - too many projects and priorities

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. We have the tools we need already at hand - we just have to make use of them. New tools are emerging, such as VoIP.

Multilingual Teams - too many technical terms and contexts

Technical content that has a clear meaning can be difficult to write. It can be equally difficult to collaborate across language and cultural barriers.

This is a challenge that arises from our success. GNU/Linux is a truly global phenomenon. Consider all the languages the Fedora Translation Project supports. It is encouraging to remember that this challenge is overcome everyday by numerous international and multinational groups.

The English language has local dialects, shades, and subtleties. Our global audience should be foremost in our minds. We should speak and write in clear, standard English. Our challenge is to write and speak English free of idioms and local color (culture) - and still be meaningful and noteworthy (have impact or pack a punch). This is done out of respect for our Fedora users for whom English is a second language, for the translation teams, and in recognition of the future of Fedora as a multilingual distribution.

SOLUTION: Use standard English and be sensitive to differences in language and culture.