User Guide

[Karsten Wade]

On Sun, Dec 07, 2008 at 06:44:06PM -0500, David Nalley wrote:
> On Sun, Dec 7, 2008 at 6:16 PM, Mani A <a.mani.cms at gmail.com> wrote:
> >  Karsten Wade <kwade at redhat.com> wrote:
> >
> >>
> >> A third option is to move entirely to covering only Fedora 10, closing
> >> out the F8 content and updating the F9 to F10.  We may need that
> >> option if we cannot get everything done with available resources.
> >
> > I believe a topic based classification of the user guide can be more helpful.
> > This way contributors can write all three releases in one place. User
> > guides for specific releases can then be generated auto-magically from
> > them.
> >
> > For example, Configuring Peripherals ---> How To Configure Mouses
> > --->[[3 Versions] ]--->[[Kde/Gnome/Xfce]]
> >
> > Best
> >
> > A. Mani
> 
> 
> The problem arises when there are material differences. For instance
> there is documentation on Pup in F8. Which is different than
> packagekit in F9 and F10
> If it were a straight copy job I suspect F9 would have already been published

The other challenge is the lack of automagic.  This is one reason I am
proposing we publish the F8 User Guide solely on the wiki.

It is possible to do multiple versions within one XML document, where
you note paragraphs with conditionals -- no tag == all get it;
per-version tag == only that version gets that content.

But that is a fair amount of work to build and maintain.  For RHEL
releases?  Worth it.  For Fedora releases?  Probably not.

There is a way to blend content in the wiki, but it would be similar
-- write it three times in one location for wherever there are
differences, then use massive transduction.  Based on what I've seen
in MediaWiki so far, trying to maintain a document that is a maze of
transduction is harder, more confusing, and raises significant
barriers to new contributors.

Where there is common content (introduction?), we could maintain that
in one master/canonical location, then transduce that in to each guide.

- Karsten
-- 
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20081208/ba18089b/attachment.bin