JohnBabich/Sandbox/Toolchain

From FedoraProject

Jump to: navigation, search

Contents

FOSS Docs Toolchain

Contents:

INTRODUCTION

FOSS Docs the FOSS Way
Although there are some fine, commercially available XML editors, the emphasis of this document is "FOSS docs the FOSS way". Just as FOSS developers have world-class FOSS interpreters/compilers and editors to write and interpret/compile code under FOSS licensing, FOSS documentation writers should have FOSS-licensed tools to create FOSS documentation. This is not an either/or (with us/against us) scenario. It's a matter of choice and freedom. Individuals and companies are free to choose a commercially-licensed package. They should also be free to choose a FOSS alternative.
Only Manual Procedure Described Initially
This document examines how to manually produce FOSS docs using only FOSS tools. This is the first objective. Once the manual procedure is well-documented, it can then be scripted via a language like Python with a substantial portion of the procedure executed as server-side code.

DESIGN ASSUMPTIONS

THE DOCUMENTATION WORKFLOW CYCLE

Image:JohnBabich_Sandbox_Toolchain_myworkflow-upd.png

The four stages in the Documentation Workflow Cycle (Patent Pending - Not!) are:

(A) Distributive editing, where writer edits documentation online wiki-style or offline with tagline-capable editor. The writer gets task assignments through Bugzilla. Material edited offline is reposted to the wiki for review and/or further revision by team members.

(B) Editorial review, wiki content reviewed by editors, before it is checked into CVS. Editorial functions include document version tracking, selection of best material from multiple versions, spell checking, and conversion of text to DocBook for storage in CVS. Note that DocBook conversion may be done manually or automatically.

(C) Persistent storage, edited DocBook document is checked into the version control system, along with its revision history. Source Control Management (SCM) can be performed using a variety of packages. The Fedora Project currently uses CVS, while Plone uses Subversion for its SCM.

(D) Static content, posted on website, generated automatically from CVS or equivalent version control system. This function would be enhanced by Plone in our scenario.

What follows is a preliminary outline of the steps within each stage.

STAGE A: Distributive Editing [Create/Edit Document]

First of all, there are two major options in editing the document.


OPTION 1: Offline via Client-side Editor

Simple GUI ASCII Text Editors:

Sophisticated Macro CLI/GUI Editors:

Advanced Markup GUI Editors:

WYSIWYG GUI Editors:

Advanced Word Processors:


OPTION 2: Online via Server-side Editor

Wiki-based Editors


STAGE B: Editorial Review [2-Stage Document Processing]

STAGE B1 - Input

STAGE B1 - Processing

STAGE B1 - Output / STAGE B2 - Input

STAGE B2 - Processing

STAGE B2 - Output

Input to Stage D

STAGE C: Persistent Storage [Check-in/Check-out]

STAGE D: Static Content [Display/Publish/Print]

A Real-world Example

This scenario mirrors the procedure for updating source code in a program.

An existing document is published as a series of HTML web pages on a web site. It also is available for downloading as a PDF document. The original source is stored in DocBook XML format in CVS. Several "bugs" are filed against the document in Bugzilla, requiring it to be updated/corrected.

Stages are not Strictly Sequential
This example illustrates that stages are not strictly sequential - for example, persistent storage (Stage C) is accessed several times throughout the process.

The following sequence of events (or workflow) occurs:

Stage A

The DocBook XML source module is checked out of CVS by a writer. The writer edits the document using the Emacs editor with PSGML and nXML mode addons. The writer thens checks the module back into CVS, requesting an editorial review.

Stage B

The editor checks out the revised document module, proofreading and validating the updated DocBook XML source.

Stage C

The editor checks the revised DocBook XML source module back into CVS and closes the Bugzilla tickets.

Stage D

The DocBook XML source is converted into valid HTML and is posted on the website as a set of web pages, complete with table of contents and an index. An updated PDF file is also generated and posted to the website for downloading.

Previous Page

Retrieved from "https://fedoraproject.org/wiki/JohnBabich/Sandbox/Toolchain"