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
Attachment:
pgpf02gRVwyor.pgp
Description: PGP signature
_______________________________________________ music mailing list music@xxxxxxxxxxxxxxxxxxxxxxx https://admin.fedoraproject.org/mailman/listinfo/music
