Improving the Docs Project workflow

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(Imported from MoinMoin)
 
(Updated this doc - should it still be marked as old?)
 
(14 intermediate revisions by 8 users not shown)
Line 1: Line 1:
= Ideas on Improving the Fedora Docs Workflow =
+
{{old}}
 +
{{header|docs}}
  
== Table of Contents ==
+
== Ideas on Improving the Fedora Docs Workflow ==
  
1. Introduction
+
=== Table of Contents ===
1. [[DocsProject/WorkFlowIdeas/AdvancingtheProject| Advancing the Project and Community]]
+
1. [[DocsProject/WorkFlowIdeas/InnovativeApproaches| Innovative Approaches]]
+
1. [[DocsProject/WorkFlowIdeas/GNOMETools| GNOME Tools]]
+
1. [[DocsProject/WorkFlowIdeas/KDETools| KDE Tools]]
+
1. [[DocsProject/WorkFlowIdeas/JavaETools| Java-based Tools]]
+
1. [[DocsProject/WorkFlowIdeas/DocWorkflowCycle| Appendix A: The Documentation Workflow Cycle]]
+
1. [[DocsProject/WorkFlowIdeas/TypesKnowledge| Appendix B: Type of Knowledge Contributions to a FOSS Project]]
+
1. [[DocsProject/WorkFlowIdeas/Components| Appendix C: Components of the FOSS Docs Toolchain]]
+
1. [[DocsProject/WorkFlowIdeas/AnotherView| Appendix D: Another View]]
+
1. [[DocsProject/WorkFlowIdeas/References| References]]
+
----
+
[[DocsProject/WorkFlowIdeas/PrintView?action=print| Full Document Print View]]
+
----
+
  
== Introduction ==
+
* [[#Introduction|Introduction]]
 +
* [[DocsProject/WorkFlowIdeas/AdvancingtheProject| Advancing the Project and Community]]
 +
* [[DocsProject/WorkFlowIdeas/InnovativeApproaches| Innovative Approaches]]
 +
* [[DocsProject/WorkFlowIdeas/GNOMETools| GNOME Tools]]
 +
* [[DocsProject/WorkFlowIdeas/KDETools| KDE Tools]]
 +
* [[DocsProject/WorkFlowIdeas/JavaETools| Java-based Tools]]
 +
* [[DocsProject/WorkFlowIdeas/DocWorkflowCycle| Appendix A: The Documentation Workflow Cycle]]
 +
* [[DocsProject/WorkFlowIdeas/TypesKnowledge| Appendix B: Type of Knowledge Contributions to a FOSS Project]]
 +
* [[DocsProject/WorkFlowIdeas/Components| Appendix C: Components of the FOSS Docs Toolchain]]
 +
* [[DocsProject/WorkFlowIdeas/AnotherView| Appendix D: Another View]]
 +
* [[DocsProject/WorkFlowIdeas/References| References]]
  
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.
+
[[DocsProject/WorkFlowIdeas/PrintView | Full Document Print View]]
  
{| border="1"
+
=== Introduction ===
|-
+
| {{Template:Note}} '''Think outside the box'''
+
|-
+
| ''New ideas, suggestions, tools and techniques are welcome.''
+
|}
+
  
{| border="1"
+
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.
|-
+
| {{Template:Important}} '''Please Add corrections '''
+
|-
+
| '''Fedora Docs Team - Please fix any inaccuracies in this section.'''
+
|}
+
  
== The Current Three-Pronged (Three Tools) Approach ==
+
{{Admon/note | Think outside the box | ''New ideas, suggestions, tools and techniques are welcome.''}}
  
=== MoinMoin Wiki - online editing ===
+
=== The Current Setup ===
  
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.
+
==== Media Wiki - online editing ====
  
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.
+
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.
  
 
ADVANTAGES: Ease-of-use, low barrier to entry, WYSIWYG editing.
 
ADVANTAGES: Ease-of-use, low barrier to entry, WYSIWYG editing.
Line 48: Line 36:
 
DISADVANTAGES: No automatic tracking of cross-references, no completely automated conversion to Doc<code></code>Book XML, markup lacks semantic meaning (provides visual formatting only).
 
DISADVANTAGES: No automatic tracking of cross-references, no completely automated conversion to Doc<code></code>Book XML, markup lacks semantic meaning (provides visual formatting only).
  
=== Plone CMS - cleaner look, content workflow ===
+
==== DocBook XML - greater flexibility ====
 
+
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.
+
 
+
ADVANTAGES: More polished presentation, improvements in document maintenance, writer <--> editor --> publisher workflow.
+
 
+
DISADVANTAGES: Learning curve in Plone, which includes Zope and Subversion.
+
 
+
=== DocBook XML - greater flexibility ===
+
  
 
A contributor can use his or her favorite editor and Doc<code></code>Book 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.
 
A contributor can use his or her favorite editor and Doc<code></code>Book 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.
Line 64: 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.  
  
=== Complexity - too many tools and techniques ===
+
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.
 
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.
Line 76: Line 60:
 
SOLUTION: Teamwork, teamwork, teamwork and tools, tools, tools
 
SOLUTION: Teamwork, teamwork, teamwork and tools, tools, tools
  
=== Coordination of Effort - too many projects and priorities ===
+
==== 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.
 
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.
Line 83: Line 67:
 
[[Communicate| Communicating and Getting Help]] .
 
[[Communicate| Communicating and Getting Help]] .
  
=== Multilingual Teams - too many technical terms and contexts ===
+
==== 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.
 
Technical content that has a clear meaning can be difficult to write.  It can be equally difficult to collaborate across language and cultural barriers.
Line 93: Line 77:
 
SOLUTION: Use standard English and be sensitive to differences in language and culture.
 
SOLUTION: Use standard English and be sensitive to differences in language and culture.
  
{| border="1"
+
{|
 
|-
 
|-
| [[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

Important.png
Old page
This 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.
DocsProject Header docTeam1.png


Contents

[edit] Ideas on Improving the Fedora Docs Workflow

[edit] Table of Contents

Full Document Print View

[edit] 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.

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

[edit] The Current Setup

[edit] 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.

ADVANTAGES: Ease-of-use, low barrier to entry, WYSIWYG editing.

DISADVANTAGES: No automatic tracking of cross-references, no completely automated conversion to DocBook XML, markup lacks semantic meaning (provides visual formatting only).

[edit] 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.

ADVANTAGES: Flexibility of editors, automatic tracking of cross-references, version tracking, standard "code" base, useful as interim code, transformable into anything, controllable with Makefile in a build system, fits into Fedora Translation and RHEL content infrastructure.

DISADVANTAGES: Learning curve in DocBook and XML (similar to HTML).

[edit] 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.

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

[edit] 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.

SOLUTION: Explain to contributors the best ways to communicate. One great guide is Communicating and Getting Help .

[edit] 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.

Next Page - Advancing the Project and Community