Guide table and BZ

[Eric Christensen]

If you haven't updated the Guide Table[1] lately, please take a look at it
and see if you can provide any updates.

I'd also like to clean up the Fedora Documentation product in BZ.  Currently
there are the following components:

   - about-fedora - General project information for main menu.
   - desktop-up2date - Keeping a desktop up-to-date using graphical tools.
   - desktop-user-guide - User guide for those new to Linux and Fedora.
   - developer-guide - Striving to be the canonical Fedora development
   reference.
   - docs-common - Common files and tools for documentation contributors.
   - documentation-guide - The Guide is the canonical set of guidelines and
   hotos for FDP contributors.
   - example-tutorial - The canonical reference document for how to use
   XML/DocBook for the FDP.
   - ftp-server - Guide to set up a full ftp server.
   - hardening - System hardening for Fedora Core 3.
   - install-guide - Installation guide for Fedora
   - jargon-buster - Striving to be the canonical glossary for all things
   Fedora.
   - mirror-tutorial - Mirroring and update services for Fedora.
   - press-release - Stylesheets and build tools for Fedora press releases.
   - proxy-guide - Building and maintaining a secure proxy server.
   - readme-burning-isos - README for burning ISO images, included at
   mirrors.
   - readme-live-image - README for inclusion in Live ISO spins
   - readme - README file for inclusion in ISO spins
   - release-notes - Fedora release notes, bugs, and requests
   - rpm-guide - RPM Guide
   - selinux-apache - Using SELinux and Apache HTTP Server in Fedora
   - selinux-faq - FAQs abut SELinux in Fedora.
   - selinux-user-guide - User guide to SELinux in Fedora.
   - software-management-guide - Software installation and maintenance on
   systems.
   - sudo-tutorial - Short tutorial on using sudo.
   - toolchain-devel - For bugs and requests of the documentation tools.
   - translation-guide - The canonical reference for translating all aspects
   of the Fedora Project
   - translation-guide-windows - Tutorial for translators working in a
   Microsoft Windows environment.
   - translation-quick-start-guide - Helping new translators get started
   quickly with Fedora translations.
   - updates - Tutorial for keeping a system up-to-date
   - usb-hotplug - Using USB and hotplug
   - xml-normalize - Development of XML normalization tools

As you can see there are quite a few components that are outdated.  I'd like
to scrub the list this week so that I can have a list to present at next
week's meeting showing what we can discard and what we need to update.

If you own one of these projects please get with me (on IRC or otherwise),
soon.  I need to verify the information that is on each of these components
including who should be assigned the ticket by default, who the QA is, and
who should be CC'd on the ticket.

If you need a component added to BZ, please let me know and we can get one
in there for you.

Thanks,
Eric


[1] http://fedoraproject.org/wiki/Docs_Project_meetings#Guides

[Paul W. Frields]

On Wed, Jun 03, 2009 at 01:40:52PM -0400, Eric Christensen wrote:
>  If you haven't updated the Guide Table[1] lately, please take a
> look at it and
>  see if you can provide any updates. 
Here are some inputs and votes, just as a Docs contributor in most
places.  Anywhere I did otherwise, I clearly noted it.

>  I'd also like to clean up the Fedora Documentation product in
> BZ.  Currently
>  there are the following components:
>  
>    • about-fedora - General project information for main menu. 
This menu item (I think) displays whether or not yelp is installed,
such as on the Live CD.  We should consider removing this item or
replacing it with something that is more programmatic like "About
GNOME," which is an application rather than a link to an installed XML
document.

Really, this is part of the release-notes component, but probably
shouldn't be.

>    • desktop-up2date - Keeping a desktop up-to-date using graphical
> tools. 
Way, way out of date.  Mostly subsumed into the
software-management-guide (q.v. below).

>    • developer-guide - Striving to be the canonical Fedora
> development
>      reference. 
Such a worthwhile reference, and so badly in need of a complete
trashing and overhaul!  I'd help with this in my spare time (?!?) if
someone took it on.

>    • docs-common - Common files and tools for documentation
> contributors. 
Has been imported to the fedora-doc-utils git repo for further
development or abandonment as needed.

This component is needed for anything that is not converted to
publican.  If everything Docs needs gets converted, this could be
abandoned and bugs closed CLOSED WONTFIX.

>    • documentation-guide - The Guide is the canonical set of
> guidelines and
>      hotos for FDP contributors. 
Karsten and a couple other people floated the idea of making this a
wiki document and not publishing it any longer.  If and when that
happens, this component could disappear and bugs would be easy to fix
by editing the wiki.

Keep in mind putting it on the wiki means we break the ability to have
the document translated with anything approaching automatic systems --
for now.  Having said that, I'm not sure how interested the
translators are in keeping this one up to date.

>    • example-tutorial - The canonical reference document for how to
> use XML/
>      DocBook for the FDP. 
Useful, but should probably live somewhere else, even the wiki as a
Media: link would be fine, in association with the documentation-guide
above.  At one time I planned to merge these but a career change got
in the way. ;-)

>    • ftp-server - Guide to set up a full ftp server. 
/me votes: Wiki-ize it.

>    • hardening - System hardening for Fedora Core 3. 
What did I do with those old CD's... :-)  Probably subsumed into the
securityguide, right?

>    • install-guide - Installation guide for Fedora 
By the way, David Nalley, thank you.  This exists in Fedora Hosted git
and it's up to the Docs team to decide if they want to record all bugs
on BZ.

>    • jargon-buster - Striving to be the canonical glossary for all
> things
>      Fedora. 
Probably could be wiki-ized with very little effort (copy/paste from
HTML and then markup simply on the wiki).

>    • mirror-tutorial - Mirroring and update services for Fedora.
Hey, my first official work for Fedora Docs, written for Fedora Core 2
originally!  Now totally busted and out of date.

/me votes: Trash it.

>    • press-release - Stylesheets and build tools for Fedora press
> releases. 
I don't think we've ever used it after the release for which it was
written.  The translation work flow for press releases didn't go off
well and I think we are unlikely to re-use this.

>    • proxy-guide - Building and maintaining a secure proxy server.
Probably also way out of date and unlikely to be fixed without an
active maintainer.  Written by a really nice guy from across the pond
-- Gavin Henry, IIRC -- who just ran out of cycles for us.

>    • readme-burning-isos - README for burning ISO images, included at
> mirrors.
>    • readme-live-image - README for inclusion in Live ISO spins
>    • readme - README file for inclusion in ISO spins
>    • release-notes - Fedora release notes, bugs, and requests 
/me votes to keep these, but that seems kind of obvious.  The plain
old "README" needs vast adjustments.

>    • rpm-guide - RPM Guide 
Still in search of an active maintainer crew, and I *know* the guys in
Brno would appreciate it now that we're on 4.7.

>    • selinux-apache - Using SELinux and Apache HTTP Server in Fedora
Karsten worked hard on a lot of these docs back in SELinux's early
days.  I think this is quite old and our targeted policy probably Just
Works(tm) in enforcing mode these days.

/me votes 50% trash it, 50% lying if I told you I looked at it before
I wrote this. :-)

>    • selinux-faq - FAQs abut SELinux in Fedora.
>    • selinux-user-guide - User guide to SELinux in Fedora. 
I think the latter is probably useful to update, but the tools have
progressed and ought to be documented to continue combatting the "just
disable SELinux" mindset.  Dan Walsh in Red Hat would be happy to
answer questions from anyone who wanted to revise this guide.  He's a
great guy and has written fabulous blog entries on the topic on a
continual basis:

http://danwalsh.livejournal.com/

>    • software-management-guide - Software installation and maintenance
> on
>      systems. 
Speaking with my FPL hat on, software management should cover
PackageKit use, including pkcon at the CLI, now that PackageKit is
present in every current Fedora distro by default.  Yum should be
handled in terms of a back end configuration engine
(yum-fastestmirror, yum-presto, yum-makemeasandwich) rather than the
first place new users turn to manage software.

>    • sudo-tutorial - Short tutorial on using sudo. 
Still useful I think, but probably could be wiki-ized, and then
dropped from BZ.

>    • toolchain-devel - For bugs and requests of the documentation
> tools. 
I guess this is subtly different from the "docs-common" component, but
I'm not sure it needs to be in BZ if the team is moving 100% to
Publican.

>    • translation-guide - The canonical reference for translating all
> aspects of
>      the Fedora Project 
Check with L10n team before doing anything with this one, I think.
There is a git repo for this guide now, but I think they still use the
BZ component for issue tracking.

>    • translation-guide-windows - Tutorial for translators working in a
> Microsoft
>      Windows environment. 
Ditto.

>    • translation-quick-start-guide - Helping new translators get
> started quickly
>      with Fedora translations. 
Tritto.  (Ha, I just made that up.)

>    • updates - Tutorial for keeping a system up-to-date 
Way out of date and should suffer the same fate as desktop-up2date, I
think.

>    • usb-hotplug - Using USB and hotplug 
With hal and udev, and now DeviceKit, this is two generations of
technology old.

/me votes: Trash it.

>    • xml-normalize - Development of XML normalization tools 
Obsolete if the team centralizes on Publican, and really it could be
subsumed in toolchain-devel in any case, if still needed at all.

>  As you can see there are quite a few components that are outdated. 
> I'd like to
>  scrub the list this week so that I can have a list to present at next week's
>  meeting showing what we can discard and what we need to update.
>  
>  If you own one of these projects please get with me (on IRC or otherwise),
>  soon.  I need to verify the information that is on each of these components
>  including who should be assigned the ticket by default, who the QA is, and who
>  should be CC'd on the ticket. 
I truly hope this helped.  Sorry I was so short in this email -- not
intended to be rude, I'm just short on time this week due to release,
and really, really wanted to be able to give you a hand with sorting
through these.

-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

[Piotr Drąg]

Paul W. Frields pisze:
> >   • translation-guide - The canonical reference for translating
> all aspects of
> >     the Fedora Project
>  Check with L10n team before doing anything with this one, I think.
>  There is a git repo for this guide now, but I think they still use the
>  BZ component for issue tracking.
> >   • translation-guide-windows - Tutorial for translators working in a Microsoft
> >     Windows environment.
>  Ditto.
> >   • translation-quick-start-guide - Helping new translators get started quickly
> >     with Fedora translations.
>  Tritto.  (Ha, I just made that up.)
>   
Actually only the third component is used and up-to-dated guide these 
days. The others need serious re-write or can be safely trashed.

-- 
Piotr Drąg
http://raven.pmail.pl

[Paul W. Frields]

On Wed, Jun 03, 2009 at 10:36:52PM +0200, Piotr Drąg wrote:
>  Paul W. Frields pisze:
> >>   • translation-guide - The canonical reference for translating all aspects of
> >>     the Fedora Project
> > Check with L10n team before doing anything with this one, I think.
> > There is a git repo for this guide now, but I think they still use the
> > BZ component for issue tracking.
> >>   • translation-guide-windows - Tutorial for translators working in a Microsoft
> >>     Windows environment.
> > Ditto.
> >>   • translation-quick-start-guide - Helping new translators get started quickly
> >>     with Fedora translations.
> > Tritto.  (Ha, I just made that up.)
> >
>
>  Actually only the third component is used and up-to-dated guide these  
>  days. The others need serious re-write or can be safely trashed. 
There may be an excellent lesson there -- if it's possible to write a
Quick Start, no one will read anything else, and you may not have to
bother with the other one. :-)

I'm pretty sure that applies mainly to community projects like Fedora,
but not more rigorous products like RHEL.  No slight intended on the
superb work produced by Red Hat documentation team writers, on whose
manuals I relied years ago for sage advice.

-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

[Ruediger Landmann]

Eric Christensen wrote:
>  If you haven't updated the Guide Table[1] lately, please take a
> look 
>  at it and see if you can provide any updates.
>
>  I'd also like to clean up the Fedora Documentation product in BZ.  
>  Currently there are the following components:
>
>      * about-fedora - General project information for main menu.
>      * readme-burning-isos - README for burning ISO images, included at
>        mirrors.
>      * readme-live-image - README for inclusion in Live ISO spins
>      * readme - README file for inclusion in ISO spins
>  
I've got versions of the above four documents converted to build in 
Publican, as well as:

* Homepage (we need to make a decision about whether to even keep this 
-- I strongly suggest killing it since it serves no useful purpose, and 
only potentially serves to confuse users)
* Accessibility (which appears to be seriously out-of-date. I've updated 
a number of URLs, but I have no idea whether this document actually 
reflects the current state of accessibility tools in Fedora)

I really don't think that any of these should be packaged with the 
Release Notes as they have been in the past.

I haven't checked any of these into the repo; the Publicanized versions 
will need attention from L10N, and I don't want to touch that until 
Transifex gets updated to version 0.6.

Finally , I plan to produce a "Quick Start" Installation Guide for F12 
to cover the "path of least resistance" for somebody to download Fedora 
and get it installed on a typical PC. This would be the Guide for a user 
who doesn't need the full documentation of the installation process and 
all its options that the IG offers. Some of this Guide will necessary 
overlap somewhat with "readme-burning-isos" and possibly make that 
smaller doc redundant.


Cheers
Rudi

[Paul W. Frields]

On Thu, Jun 04, 2009 at 08:43:47AM +1000, Ruediger Landmann wrote:
>  Eric Christensen wrote:
> > If you haven't updated the Guide Table[1] lately, please take a look at 
> > it and see if you can provide any updates.
> >
> > I'd also like to clean up the Fedora Documentation product in BZ.   
> > Currently there are the following components:
> >
> >     * about-fedora - General project information for main menu.
> >     * readme-burning-isos - README for burning ISO images, included at
> >       mirrors.
> >     * readme-live-image - README for inclusion in Live ISO spins
> >     * readme - README file for inclusion in ISO spins
> >
>  I've got versions of the above four documents converted to build in  
>  Publican, as well as:
>
>  * Homepage (we need to make a decision about whether to even keep this -- 
>  I strongly suggest killing it since it serves no useful purpose, and only 
>  potentially serves to confuse users)
>  * Accessibility (which appears to be seriously out-of-date. I've updated  
>  a number of URLs, but I have no idea whether this document actually  
>  reflects the current state of accessibility tools in Fedora) 
Pretty sure it doesn't reflect the current state.

>  I really don't think that any of these should be packaged with
> the  
>  Release Notes as they have been in the past. 
There may be some requirement for an accessibility statement, but I'm
not sure that really applies to Fedora; it may in fact be a holdover
from the Red Hat Linux days that's simply stayed around like a weed.
May be worth checking with Fedora Legal on the fedora-legal-list?

>  I haven't checked any of these into the repo; the Publicanized
> versions  
>  will need attention from L10N, and I don't want to touch that until  
>  Transifex gets updated to version 0.6.
>
>  Finally , I plan to produce a "Quick Start" Installation Guide for F12 to 
>  cover the "path of least resistance" for somebody to download Fedora and 
>  get it installed on a typical PC. This would be the Guide for a user who 
>  doesn't need the full documentation of the installation process and all 
>  its options that the IG offers. Some of this Guide will necessary overlap 
>  somewhat with "readme-burning-isos" and possibly make that smaller doc 
>  redundant. 
Superb!  Maybe you can use some common content as snippets in the
Quick Start?  Your call.

-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

[Eric Christensen]

On Wed, 2009-06-03 at 13:40 -0400, Eric Christensen wrote:
>  If you haven't updated the Guide Table[1] lately, please take a
> look
>  at it and see if you can provide any updates.
>  Thanks,
>  Eric 
I've moved the table I emailed to the wiki[1] and sorted it out into
categories based on other people's input.  Please look over it and
comment/move stuff as necessary.  I want to have this finished during
tomorrow's meeting.

Eric