On Fri, Jul 30, 2010 at 08:40:44PM -0400, Christopher R. Antila wrote:
Hi:
The Fedora Musicians' Guide is an official document being prepared by the
Documentation Project. This carries much more weight than a wiki.
That said, increased participation would be great, and the Musicians' Guide
is already on the Fedora wiki in my User: pages. These could easily be
transferred into the real wiki, and maintained in sync or independently of
the official documentation, but I don't know if that sort of duplication is
a good idea. What we certainly could do is write complementary chapters
with programs that aren't (yet) in the official guide. Besides, as an
open-source project, the official guide itself is already like a wiki in
that people with free time can contribute with what they know best.
This is the hard fence we have to straddle with documentation in
Fedora. The wiki is a significantly lower barrier to entry, so 10x to
100x more people may work on a document, but it is a significantly
high barrier to working with the rest of Fedora in terms of
internationalization (i18n), localization (l10n), and document
management.
The release notes are rewritten each release on the wiki since most of
the material changes so much that it's OK to throw away 70% of the
writing and l10n of the previous release. People add content to
various pages, and the writing team massages it, then converts it to
XML.
A book such as the Fedora Installation Guide changes relatively little
for each release and so is kept in DocBook XML under the Publican
toolchain, with a smaller team of writers doing the updates. People
file bugs to get fixes done instead of editing the wiki.
So, it would not be trivial to reconvert from the wiki all the changes
and updates that an active community can keep there. Instead I would
propose a complementary scheme such as:
* Fedora Musician's Guide remains a stand-alone guide that focuses on
getting started using one or a few specific applications from each
area of audio tooling needs (recording, mixing, scoring, etc.)
* On the wiki are a number of stand-alone pages such as [[Scoring
music with Foo Bar]]. People who like to use that tool can help
write those pages and not worry about the other pages. They are all
part of a set of categories so they can be easily found together.
* A single wiki page e.g. [[Using audio tools with Fedora]] has a
table of contents that lists all of the stand-alone
application-specifi wiki pages. It also has some introductory
material, reference material, and any other new page ideas that
people have.
* The Musician's Guide regularly points the reader to that wiki-based
guide and set of pages for updated information. For example, the
guide can cover Audacity, and there can be a matching [[Using
Audacity in Fedora]] wiki page. The wiki page can cover 10x the
number of items that you want to cover in the guide, and be kept up
to date for the latest software in the repository. So, the
Musician's Guide is the starting point, and it does a hand-off to
the wiki at the end of its lessons.
* Every iteration of Fedora, the writers working on the Musician's
Guide look over the content changes done on the wiki (using history
pages, their own experience, etc.) Think of the wiki pages as an
upstream source repository that is full of baked and half-baked
code. The Musician's Guide picks from the best and most useful, or
new and interesting, or whatever, and updates or includes that
content in the next release of the guide.
This scheme gives two types of documentation: a fixed release guide
that can be printed and referenced; a more flowing set of wiki pages
with various quantities and qualities of information.
All of the above basically presumes an active audio SIG, but it also
is fault-tolerant. If a group of enthusiasts about a particular tool
stop writing about it, it doesn't stop the whole train. The
Musician's Guide can continue being updated, or not, without
interfering with the work on the wiki. The wiki work can draw more
instant gratification collaboration and help make the Fedora pages a
great reference for using all these tools under Fedora.
- Karsten
--
name: Karsten 'quaid' Wade, Sr. Community Gardener
team: Red Hat Community Architecture
uri:
http://TheOpenSourceWay.org/wiki
gpg: AD0E0C41