Guide table and BZ

Paul W. Frields stickster at gmail.com
Wed Jun 3 20:26:15 UTC 2009


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




More information about the docs mailing list