On Wed, 2004-08-11 at 09:27, Karsten Wade wrote:
> >
> > Comment. I'm nervous about the number of 'titles' around? (Roles)
>
> These aren't empty titles, they are roles to be fulfilled in a process.
> Not intended to add bureaucracy, just layers to get stuff done and make
> sure it is of a consistent quality.
In which case its rephrasing then? 'The following tasks need doing'
or 'terminology'?
>
> > Agree the jobs need doing;
> > Some 'titles' aren't mentioned again? (package maintainer)
>
> Somewhere toward the end I mention that we may want to have a
> fedora-docs RPM that goes in Core, Extras, etc., which contains a
> snapshot of documentation for the related version of FC. That package
> would need a maintainer, in addition to having a process to decide what
> goes into the package.
OK, I misunderstood... or it wasn't clear. You decide.
>
> > Specifics:
> > Invalid use for emacs.
> > If you want your xml tidying up say so.
> > XSLT can indent nicely with no content change. (identity transform,
> > output set to indent=yes.
>
> I'll disagree about that being a valid use of Emacs, but whatever. ;-)
>
> You can't blindly indent the document and walk away. If you anything in
> a <screen> or <programlisting> block that requires specific formatting
> (white space, etc.) -- such as code from a program, example from a
> config file, or a series of command line examples -- doing a DTD based
> indent will likely mess up those sections. If that is not true, I'd be
> very happy to see a demonstration. Otherwise, I will continue to
> manually C-c C-q my XML in Emacs.
Yes. For docbook just list the element names requiring whitespace
retaining. The rest get 'tidied' up.
<xsl:strip-space elements="*"/>
<xsl:preserve-space elements="programlisting screen literallayout
...."/>
>
> Not a problem to do it myself, just wanted to get it more set in
> sandstone before going over from plain text. :)
OK
Save you 5 mins.
--
Regards DaveP.
XSLT&Docbook FAQ
http://www.dpawson.co.uk/xsl
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
"/sgml/oasis/docbookx.dtd" [
<!ENTITY RH "Red Hat"> <!--The generic term "Red Hat" -->
<!ENTITY RHL "Red Hat Linux"> <!--The generic term "Red Hat Linux" -->
<!ENTITY RHEL "Red Hat Enterprise Linux"> <!--The generic term "Red Hat Enterprise Linux" -->
<!ENTITY RHN "Red Hat Network"> <!--The generic term "Red Hat Network" -->
<!ENTITY FORMAL-RHI "&RH;, Inc."> <!--The generic term "Red Hat, Inc. -->
<!ENTITY PROJECT "Fedora project"> <!-- Set the project name -->
<!ENTITY NAME-TITLE "Fedora Project"> <!-- Set the project name, use for titles -->
<!ENTITY DISTRO "Fedora Core"> <!-- Set the distro name -->
<!ENTITY BOOKID "jargon-buster-1.8 (2004-01-30)"> <!-- change version of manual and date here -->
<!ENTITY LEGALNOTICE SYSTEM "../common/legalnotice-en.xml">
]>
<article>
<title>The Writing Lifecycle for Fedora Docs Project (FDP)</title>
<articleinfo>
<revhistory>
<revision>
<revnumber>1.0</revnumber>
<date>11 Aug 2004</date>
<authorinitials>DaveP</authorinitials>
<revdescription><para>Initial Release</para> </revdescription>
</revision>
</revhistory>
&LEGALNOTICE;
</articleinfo>
<note>
<para>This is a process document, written in a style to describe systems as
if they exist. In this document, the reader (you) are treated as
someone coming into and through the project as a contributor.</para>
<para>When this process doc describes the system at the level we want to
start interacting with it, components can be chunked and parsed to
small groups for iteration and contribution.</para>
<para>
Ultimately, this process should be a stand alone document or
incorporated into the Doc Guide. Bits that are referenced but remain
unwritten are marked (unwritten).</para>
</note>
<sect1>
<title>Roles defined in this process:</title>
<simplelist>
<member>* Author, who author content and/or XML; for example, two people can
work together, one doing the content, the other converting to XML.
</member>
<member>* Editor(s), presumably a group maybe with a separate mailing list,
who have go/no-go control over what gets published on
fedora.redhat.com/docs. The FDP maintainer/leader(s) are de facto
members of this group, but do not exert final authority. Editors
must reach consensus (or majority opinion?).
</member>
<member>* Maintainer of fedora-docs in CVS, who interacts with the overall
Fedora CVS maintainer.
</member>
<member>* Maintainer of website, specifically fedora.redhat.com/projects/docs
and fedora.redhat.com/docs.
</member>
<member>* Package maintainer for fedora-docs RPM in Core/Extras.
</member>
<member>* Recipient of bugs to fedora-docs.
</member>
</simplelist>
<para>A single person can fill one or more roles, just as a single role can
be fulfilled by one or more persons.</para>
<sect2>
<title>Read This</title>
<para> It is presumed that a writer with a contribution or interested in
contributing will do the following:</para>
<orderedlist>
<listitem>
<para> Read at least the (unwritten) Docs Quick Start Guide</para></listitem>
<listitem>
<para> Know what documents exist {Link to appropriate URLs}</para></listitem>
<listitem>
<para> Know what ideas don't have authors (unwritten) {Link to
appropriate URLs}</para>
</listitem></orderedlist>
<para> One thing to do: introduce yourself to the group. Use the self
introduction method described at
http://www.fedora.us/wiki/SelfIntroduction. This is how it is done
on fedora-devel-list.</para>
</sect2>
</sect1>
<sect1>
<title>From Idea to Assignment</title>
<sect2 id="s1.1">
<title> You Have An Idea</title>
<para> If you have a specific idea in mind, consider your idea in the
context of the existing materials. Ask yourself some questions:</para>
<orderedlist>
<listitem>
<para> Does it build on a previous work?</para> </listitem>
<listitem>
<para>Does it help create a set of documents with related themes?</para></listitem>
<listitem>
<para>Is it a group or solo project? If a group, how can you interest
others?
</para></listitem>
<listitem>
<para>What need does your tutorial fulfill?</para></listitem>
<listitem>
<para>Are you willing to maintain this document?</para></listitem>
</orderedlist>
<para> With that in mind, you can bring your idea to the list. Tell us
about it, with your answers to the above questions included.
Accept some feedback. You want to get to a point where the
consensus is, "Yes, that is a good idea, proceed, we'll include it
in the Fedora docs repository." Project members will keep in mind
your previous posts to the list, other work you've done here and
other locations, information from your self-introduction, the
quality of your idea, and your level of commitment to it.</para>
<para> A fully realized idea ready for writing should have the following
completed for it:</para>
<orderedlist>
<listitem>
<para>A scope or charter describing what problem the tutorial solves
and how it goes about solving it.</para>
</listitem>
<listitem>
<para> One or more authors (count yourself).</para></listitem>
<listitem>
<para>One or more willing editors/testers (don't count yourself).</para></listitem>
<listitem>
<para>A strawman schedule, mainly focusing on milestone generation.
Associate them with dates for convenience; the goal is to have a
list of milestones which show progress towards completion.
</para></listitem>
</orderedlist>
</sect2>
<sect2>
<title> You Don't Have An Idea</title>
<para> If you don't have a specific idea for a tutorial in mind, you will
need to find an assignment.</para>
<orderedlist>
<listitem>
<para> There is a list of open assignments at {URL}. (unwritten)</para></listitem>
<listitem>
<para> Ask on the list or look through existing tutorials, find out if
anyone needs assistance authoring or maintaining.
</para></listitem>
<listitem>
<para>Look around on the Web for useful tutorials written for early
versions of Red Hat Linux or other distributions, and consider
if they will be useful to port over to Fedora Core. If you find
one, go through the process described in <xref linkend="s1.1"/></para>
</listitem>
<para>Ultimately, any idea you have will require some form of the work
done in <xref linkend="s1.1"/> to get the idea accepted for publication.</para>
</sect2>
</sect1>
<sect1>
<title>From Assignment to Production</title>
<sect2>
<title>What You Need to Know</title>
<para> These are items you need to know, guidelines to follow, when
writing your tutorial. Remember to </para>
<para> Read the full Doc Guide. If you are not authoring natively in
XML and will be seeking conversion, you will still need to be
familiar with the other processes outlined in the Doc Guide.
Read the chapter on Writing Not in DocBook in both the Quick
Start and Doc Guide (unwritten). Look at other editor specific
chapters in the Doc Guide (unwritten) if you need them.</para>
<para>Read the Style Guide. This is a collection of appropriate
materials that tell you the style in which you need to write,
guide you on grammar, specify word choice, and demystify
terminology. (unwritten)</para>
<para> Follow the System Documenting Guidelines in the Doc Guide
(unwritten), which specify how to eliminate variables that are
not common to a Fedora Core installation. For example, using a
default, fresh user account removes dependency on .bash* file
tricks. These include best practices for technology usage, such
as using rpm packages instead of tarballs. We might choose to
have equal preferences for equivalent technologies, such as
up2date and yum. Reminder to document the existing system, not
provide "fixes" that make a system unsupportable, abnormal, or
otherwise _more_ difficult to maintain.</para>
<para> One of the reasons for using Emacs is that it is capable of
indenting the code according to the DTD. It is essential for
sane CVS diffs that we all stick to the proper indent
formatting. For translation purposes, we may not want to
reformat during a translation cycle, as that can throw off the
line count for diff tools. Regardless of what tool used to
author the XML, it _must_ follow the formatting guidelines
defined in the Doc Guide.</para>
<para> If you are authoring in XML, prepare your directories according
to the example-tutorial and as outlined in the Doc Guide.</para>
</sect2>
<sect2>
<title> What You Need to Do</title>
<para> Documentation is harder to "release early, release often" than are
applications. A broken document can be far more serious than an
app segfaulting. However, you don't want to be writing your
document in a vacuum, without the benefit of collaborating with
peers. It is fine to show it to friends, family, and foes, but it
should be noted that it is BETA or DRAFT documentation, and anyone
who is fool enough to trust it gets to keep both pieces when it
breaks.</para>
<para>
You are encouraged to host your work-in-progress (WIP) on a
personal webpage, in order to show to project peers. Remember to
make the .xml or other source available. If you do not have usable
Web space, look for willing hosting partners in the project, who can
build and host your beta documents.</para>
<para> If possible, accept patches to your document as XML patches. This
makes it easier for peers to offer fixes.</para>
</sect2>
</sect1>
<sect1>
<title>From Production to Posted</title>
<para>
At this part of the process, a document has to undergo peer
editing, both of content and XML. Posting to the mailing list is
the currently accepted process; the editors group may choose to add
more process in here.</para>
<orderedlist>
<listitem>
Open a bugzilla ticket, setting the Severity: to "enhancement".
Include in this bug the state of the document, the location of
the HTML, XML, and PDF if you choose. If you have permission,
set the bug to block the New Doc Submission tracker bug
XXXXXX. (unwritten)
<note>
<para>This needs clarification</para>
</note>
</listitem>
<listitem>
<para>Send an email to the mailing list, with the same
information as in the bug report, and the bz number. Any editor
can receive the submission by adding the block to the tracker
bug, and accepting the bug Assignment for themselves or for the
editors (if the editors have a separate mailing list and
associated bugzilla account, e.g. fedora-docs-editors-list.)
(unwritten)</para></listitem>
<listitem>
<para> Get editors engaged in reading the content and XML source. Fix
and fight and fix and fight and fix and fight and fix and
finally feast. Work well with your editors. Do it publicly.
Use the bug report to track changes, discussions, and comments,
with URL links back to mailing list threads.
</para></listitem>
<listitem>
<para> When the editor(s) have approved your document for publication,
the ticket is assigned to you. Prepare the directory for CVS
into a tarball. If you do not know how to do this, refer to the
chapter Preparing Your Document for CVS in the Doc Guide
(unwritten); if that doesn't help, ask your editor for
assistance.
</para></listitem>
<listitem>
<para> Attach a link to the tarball to the bz report, or even the
tarball attached itself if small enough, and assign the ticket
to the maintainer of the fedora-docs CVS module. When CVS-fu is
complete, the ticket is assigned back to the editor(s).
</para></listitem>
<listitem>
<para> At this point, work continues in CVS. If you don't have CVS
access, get it. Read about how to use CVS in the Doc Guide.
</para></listitem>
</orderedlist>
<para>
A final snapshot is defined as ready to post to the world as
Fedora documentation when the editor(s) and the author(s) come
to a consensus. The ticket is then assigned to the maintainer
of fedora.redhat.com/docs, who finally posts the document into
the doc tree. The Web maintainer either closes the ticket, or
reassigns it to the author or editor(s) to handle.</para>
<para>
An active new document may keep the same ticket open, spawn several
sub-tickets and other bug reports blocking the main ticket, and/or
reused for continuous posting. An infrequently changed document
can close this ticket and open a new one when new changes are
desired.</para>
</sect1>
<sect1>
<title> From Posted to Maintained</title>
<para>
Once a document is posted, the lifecycle switches into the
maintenance mode.</para>
<para>
When there are sufficient documents to make it worthwhile, the
Fedora docs project may start maintaining an RPM of documents to
ship with Fedora Core, Extras, or another channel
(fedora-docs-en-*.rpm). If you or anyone feels your document should be
included in that list, it will need a bug report requesting the
enhancement, and go through the editors for approval. Once
approved, the bug is assigned to the maintainer of the fedora-docs
package.</para>
<para>
If a translator is interested in translating the document, a
request for enhancement bug report should be filed. Similarly,
such a translated document can be included in a language specific
version of the fedora-docs package.</para>
<sect2>
<title> Maintenance Lifecycle</title>
<para> When a test release is made, that is the time to review your
document against the latest reality. If you find a discrepancy
or change, you may want to track down the developer and find out
how it's likely to end up for final release. Usually you are
targeting your update for the release, but there are rare
occasions where you update a document for each release, such as
the release-notes or a specific FAQ.
</para>
<para> When bugs come in against your document, the receiver of bugs to
fedora-docs will reassign the bug to you for fixing. Respond in
a timely fashion, get clarity from the reporter if needed, and
update the document in CVS to reflect the change, noting the bz
report number in the CVS changelog. When the bug is ready to
close, change to QA_READY (feature unwritten?). An editor will
check the change, and if approved, assign the bug to the website
maintainer, who will handle the posting to /docs and close the
bug.</para>
<note>
<para> NOTE: Don't forget to update the version number of your document
when you post a new version. This helps immensely when tracking
bugs in bugzilla, where the version number should be specified
by the reporter. Remember that you may end up maintaining
different documents depending on the version of Fedora Core.</para>
</note>
<para> There is likely a reason to maintain an old document for at
least one or more versions of FC. A worthy document can be
carried on by the Fedora Legacy project, if they see fit, when a
version of FC is handed off by the FC developers to the Legacy
project. If you do find that it's necessary to maintain
multiple versions, you will want to have the CVS branched. File
a bug report for that, assigned to the fedora-docs CVS
maintainer, who may pass the ticket on to the FC CVS maintainer.</para>
<para> If you come to a time when you realize you no longer want to or
are able to maintain your document, you should evaluate if the
document deserves to be continued. Either way, announce to the
mailing list and specifically the editor(s) about your decision
and recommendations about the fate of your document. If
possible, look for a person to hand-off maintenance to, and work
with him/her/them for as long as possible to do the hand-off.
For more details, see the (unwritten) chapter in the Doc Guide
about document hand-off.</para>
</sect2>
</sect1>
</article>
