[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
  Web www.spinics.net

Re: [PlanetCCRMA] Music Spin

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

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

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

Attachment: pgpf02gRVwyor.pgp
Description: PGP signature

music mailing list

[Fedora Legacy Announce]     [Fedora Extras]     [Home]     [Kernel]     [Fedora Legacy]     [Fedora Desktop]     [Fedora Directory]     [PAM]     [Red Hat Development]     [Red Hat 9 Bible]     [Red Hat 9]     [Big List of Linux Books]     [Gimp]     [Yosemite News]     [Yosemite Camping]

Powered by Linux