Section II. B. 1 2 and 3 of Documentation Guide V2
Karsten Wade
kwade at redhat.com
Fri May 19 15:41:38 UTC 2006
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 at edward ~]$ rpm -qa up2date
> up2date-4.4.23-4
> [edward at 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/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20060519/0c0bec9b/attachment.sig>
More information about the fedora-docs-list
mailing list