On Tue, 2006-05-16 at 16:44 -1000, Edward Haddock wrote:
Aloha all,
I have the aforementioned pieces done.
Are these just offline? I haven't seen them appear in the Wiki, but I
don't watch everything. :)
I want to make sure I understand where these pieces fit in, especially
with the new draft outline/structure of the Documentation Guide. Or is
this more of the Quick Start Guide variety, that could also be an intro
chapter within the overall Doc Guide?
Sorry that I'm surely missing a bit of context, from something I've
missed on list. Please fill in my blank spots, at least here where you
can. ;-D
It is mostly links to some other
pages and could be combined at some point. Please find it copied into
this email following. Hopefully this helps.
Fantastic, thanks.
Paul and I are intending on doing a small hack fest with the two of us
when we are in person together the week after next. We haven't set a
solid time yet, but it occurs to me that you and others involved in the
future of the Documentation Guide and our project's guidelines can work
with us at remote. A little different, but worth it. :)
More comments inline:
=====
1.) The first step in joining the Fedora Documentation Project is to
join the community and engage in the discussion. Subscribe to the
fedora-docs-list, fedora-dsco-list and fedora-announce-list to keep up
to date and informed about the project and Fedora in general. The links
can be found at
https://listman.redhat.com/mailman/listinfo/fedora-docs-list,
http://www.redhat.com/mailman/listinfo/fedora-announce-list and
https://www.redhat.com/mailman/listinfo/fedora-dsco-list. After visiting
the pages and filling in the needed information an automated email
message will be sent. Choose to follow the link or respond to the email
as outlined in the instructions contained in the emails. Please note
that to be part of the Fedora Documentation Project you have to join the
fedora-docs-list.
Good and to the point.
Do you think it helps visually to have the URLs in a list (bulleted)?
A good rule of thumb is, when you find yourself writing "Note this and
that", that is a good time to put in an admonition. If an admonition
seems too much/more than is required, then I often drop the "note",
"important", etc. wording. This reduces confusion about notes and
Notes, and helps keep from alarmist writing. :)
|| {i} '''To be part of the Fedora Documentation Project, you must
join [URL fedora-docs-list]''' ||
<note>
<title>You must join fedora-docs-list</title>
<para>
To be part of the Fedora Documentation Project, you must join
<ulink url="URL">fedora-docs-list</ulink>.
</para>
</note>
2.) Next, ensure that the proper tool chain is installed. The first
Stylistically, I've been using 'toolchain'. We can decide what we like
as a group, and put that in our style guidelines.
Long stale working draft at:
http://fedoraproject.org/wiki/DocsProject/StyleGuidelines
tools that should be installed are Yum and/or up2date.
AIUI, up2date is deprecated. For GUI package management, refer to Pup
and Pirut.
These Software
Management Utilities will ensure that all software packages are current
and aid in installing those not already installed. Both are installed by
default on Fedora Core 5 but this can be checked using rpm.
[edward@edward ~]$ rpm -qa up2date
up2date-4.4.23-4
[edward@edward ~]$ rpm -qa yum
yum-2.4.1-1.fc
Either package will work for managing software packages.
You can link to
http://fedora.redhat.com/docs/yum/.
After that, setup Privacy Guard Software and utilities to manage
the
GPG keys. Use GPG to identify yourself and authenticate your
communications, even with people you don't know. GPG allows anyone
reading a GPG-signed email to verify its authorship. In other words, GPG
allows someone to be reasonably certain that communications signed by
you actually come from you. GPG is useful because it helps prevent
mischievous third parties from polluting code or conversations by
masquerading as other entities. To participate in any part of the Fedora
Project,
- you should have a GPG key pair, and
- your public key must be available on
pgp.mit.edu, a well-known public
keyserver.
Some Privacy Guard Software and Management Utilities include:
I.) GnuPG
http://fedoraproject.org/wiki/Cryptography has a wonderful explanation
on how to install openssh and GnuPG.
II.) Seahorse
Seahorse is a GUI utility to manage keys. Go to
http://seahorse.sourceforge.net/ for information on installing and using
this utility.
III.) KGpg
KGpg is the KDE GPG key manager and can be installed via yum if not
already installed. Information and instructions can be found at
http://developer.kde.org/~kgpg/
If either of these last two are not in Core or Extras, we have to take a
moment here to consider.
By rule and practice, Fedora Documentation only documents what is in
Core, and now Extras. There are always other programs that people like,
but obviously our first mission is to document what is in the distro.
That said, documenting for _ourselves_ (for the project teams) has an
additional imperative. This is why the Wiki is probably full of
suggestions to use various non-Core/Extras packages to get work done.
To me, this is acceptable, along as:
1. Reasonable effort is made on our part to find and support in-distro
packages first. If they do not exist or are too broken to use, we file
a bug/supportive comment.
2. We note that these are out of distro and all that might entail.
An editor also needs to be installed to work with documents. Vi,
Emacs
and
OpenOffice.org Writer will all work and it is mostly a matter of
preference. Last but certainly not least, see if a few handy utilities
to process documents are installed. CVS, xmlto and/or the Docbook files
to work with the Wiki are all useful and necessary.
I think you are mixing up usages a bit. The DocBook and the Wiki are
not really related at this point.
There is a group that covers the DocBook and Emacs pieces:
su -c 'yum groupinstall ...'
I just forget the group name right now. :)
3.) After GnuPG is installed go to
http://fedoraproject.org/wiki/DocsProject/UsingGpg/CreatingKeys and
follow the instructions there to generate a GPG key pair. For additional
information the Legacy site
http://www.fedoraproject.org/wiki/Legacy/PGPHowTo has a lot of good
information on key pair generation and use as well.
The second doesn't need to reference the Legacy site, just say that it
is another good resource.
Then setup your email program to work with GnuPG so that signing
and
verification of emails is possible. Instructions for each can be found
as follows:
I.) Evolution
A helpful page is located at
http://fedoraproject.org/wiki/DocsProject/UsingGpg/WithEvolution
II.) Thunderbird
Has help located here,
http://fedoraproject.org/wiki/DocsProject/UsingGpg/WithThunderbird
III.) Kmail
Located here
http://fedoraproject.org/wiki/DocsProject/UsingGpg/WithKmail is still a
work in progress and
IV.) Pine
Located here
http://fedoraproject.org/wiki/DocsProject/UsingGpg/WithKmail is also a
work in progress.
This really shows that all the pieces we need are around, they just need
to be stitched together, either by linking or copying/moving content.
Cool.
Thanks - Karsten
--
Karsten Wade, RHCE * Sr. Editor *
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Fedora Documentation Project
http://fedoraproject.org/wiki/DocsProject
Learn. Network. Experience open source.
Red Hat Summit Nashville | May 30 - June 2, 2006
Learn more:
http://www.redhat.com/promo/summit/