Re: Are Fedora docs readable?
by Karsten Wade
On Tue, 2005-05-10 at 23:00 +0100, Timothy Murphy wrote:
> On Tue 10 May 2005 12:47, Karsten Wade wrote:
>
> > I do not see the word "document" in the title. Aside from that, your
> > argument is specious. This is open source software we are using, the
> > ultimate documentation is _always_ the source code. Your inability to
> > understand it does not make it any less valid. Sorry if that is harsh,
> > but it's a common truth.
>
> It's not particularly harsh, just silly.
> If someone googles for "Fedora tutorial" or whatever,
> and is directed to an unreadable article,
> with no instructions as to how to make it readable,
> they will conclude that Fedora is for pointy-heads.
When you come up with the secret formula for controlling what Google
returns, let us know. Otherwise, we can't be responsible for Google
finding an informal, alpha document for a version of Fedora Core we no
longer document.
- Karsten
--
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
18 years, 10 months
Self-Introduction: Andrew Jones
by Andrew Jones
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Full name:
Andrew Jones
City, County:
Bath, Somerset, UK
Profession:
Student
School:
The University Of Bath
Goals:
I'd like to write documents targeted at new users. I've been using linux
exclusively for a while, but I can still remember what it was like to be
a new at it. I'm happy to edit for grammar/spelling and technical accuracy.
Qualifications:
No paper qualifications. My knowledge has come from installing linux to
use as a desktop, and for a few servers for home networks. I know a bit
about the obvious things that most servers need (dns, dhcp, samba and so
on). I'm taking a networking course at university so understand the
fundamentals well.
I program C well, and Python not so well, but would be interested in
developing these skills in parallel with (perhaps even because of) the
doc project.
Cheers,
Andrew
GPGKey:
pub 1024D/385622CD 2005-05-09 [expires: 2006-05-09]
Key fingerprint = 08AE 82DB 3029 E1DA 7066 1265 220C AEB1 3856 22CD
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org
iD8DBQFCgRAwIgyusThWIs0RAjUDAJ4k308Y73n5yIw/k0hu4aetLg5/uwCdFTMf
WXw2AEDXKXCYSnzrM5j70yI=
=tD8c
-----END PGP SIGNATURE-----
18 years, 10 months
Are Fedora docs readable?
by Timothy Murphy
I was looking for a document that would explain
how Linux/Fedora decides what driver to use
with a given USB device,
and google directed me to usb-hotplug-tutorial.
Unfortunately this appeared to be in XML,
and required a DTD which I could not find.
Are these documents currently unreadable?
If not, perhaps a link to an explanation
of how to process them might be in order.
--
Timothy Murphy
e-mail (<80k only): tim /at/ birdsnest.maths.tcd.ie
tel: +353-86-2336090, +353-1-2842366
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
18 years, 10 months
Self-Introduction: Gavin Henry
by Gavin Henry
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Full legal name:
Gavin Clive Henry
City, Country:
Aberdeen, Scotland
Profession or Student status:
Managing Director
Company or School:
Suretec Systems Ltd.
Your goals in the Fedora Project:
What do you want to write about?
OpenLDAP, Squid, Amanda, Samba, Postgresql, Exim, SSH and anything
network/server/security related.
What other documentation do you want to see published?
Comprehensive User Guide and documentation somewhat simliar to the
versions of Red Hat Enterprise Linux
Do you want to edit for grammar/writing and/or technical accuracy?
Yes.
Anything else special?
Help create a better toolchain for PDF generation and help gather new
writers/editors.
Also, help maintain a successful documentation project.
Historical qualifications:
What other projects or writing have you worked on in the past?
I help maintain: [http://www.amanda.org/docs/using.html The Official
Amanda Guide]
I also have authored serveral documents for my company, which will be
released to the Fedora Docs Project in the near future.
What level and type of computer skills do you have?
If I may say so, Expert.
What other skills do you have that might be applicable? User interface
design, other so-called soft skills (people skills), programming, etc.
People skills, friendly personallity and programming experience, as well
as expert Linux Admin skills.
What makes you an excellent match for the project?
Read above ;-)
GPG KEYID and fingerprint:
[ghenry@suretec ~]$ gpg --fingerprint DB73BEA8
pub 1024D/DB73BEA8 2003-09-28 Gavin Henry (Suretec Systems)
<ghenry(a)suretecsystems.com>
Key fingerprint = 0391 864C 2CBB 4756 D817 CE40 796B 1E87 DB73 BEA8
sub 2048g/765253B8 2003-09-28
- --
Kind Regards,
Gavin Henry.
Managing Director.
T +44 (0) 1224 279484
M +44 (0) 7930 323266
F +44 (0) 1224 742001
E ghenry(a)suretecsystems.com
Open Source. Open Solutions(tm).
http://www.suretecsystems.com/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.6 (GNU/Linux)
iD8DBQFCgLSweWseh9tzvqgRAsvXAJ9SfssvsRxzbnF9DPxdXBZUqSH0aQCeNgml
Ot5nJO0vUged2Icmt384rYM=
=jmyO
-----END PGP SIGNATURE-----
18 years, 10 months
Minutes from FDSCo (03-May-2005)
by Karsten Wade
## For those wondering what is happening in the Documentation Project:
Fedora Documentation Steering Committee (FDSCo)
03-MAY-2005 #fedora-docs on irc.freenode.net
Attendees:
==========
Karsten Wade (chair)
Tommy Reynolds
Tammy Fox
Gavin Henry
Paul Frields
Stuart Ellis
New Actions:
============
FDSCo: Find ways to get fame to documentors. Name up in lights. Etc.
FDSCo: You can post a link to your own self-intro or similar on your
Wiki page.
FDSCo: Take the divided list of writers who have volunteered and
contact them directly to see what help they need, or what their
status and interest is.
Gavin: To make a Wiki Contributors page that incorporates the Writers
and Editors pages somehow, linking to Self-Intros. This is
part of the "find the interested writers" sub-project.
Gavin: Hunt fedoraforum.org for doc ideas and writers.
Gavin: To look into getting a FDSCo interview on lugradio.org.
Paul/Karsten: FDL for the new style chapter
Karsten: Assign task of making docs use common files in ./ instead of
../, in order to work for separate modules per document.
Karsten: Deliver minutes that are better organized, using the FESCO
minutes as an example. Will start posting to fedora-announce
as well as fedora-docs-list.
Karsten: Look into reordering CVS to make all documents in fedora-docs
module into separate modules.
Tommy: Convert tasks into a schedule, split out goals, borrowing from
Extras template.
Tammy: How to create a new CVS module, for the Doc Guide.
Tammy: Look into ViewCVS. One objective is to get regular reports of
activity on documentation, in order to help define abandoned
docs.
Tammy: Looking into sponsorship of Doc Days and similar incentives for
community participation.
Action Status:
==============
* New writers will find this page very useful in getting started:
http://fedoraproject.org/wiki/DocsProject/NewWriters
* Details on gaining CVS access are available at:
http://fedoraproject.org/wiki/DocsProject/CvsUsage
* Stuart has made signficant progress on tracking the status of all
documents ever proposed or in the works, pulling together
information from disparate locations.
http://fedoraproject.org/wiki/DocsProject/EditorAssignments
* Paul and Karsten have the first iteration of the style guidelines
put into the Doc Guide. These are required reading for writers and
editors to be able to work together.
http://fedora.redhat.com/participate/documentation-guide/ch-style.html
* Karsten announced the style changes and noted they are required
reading for writers and editors.
* CVS is available at /cvs/docs for all documentation projects.
Discussion Results:
===================
IDEA: A Docs Day, contest/competition with booty/prizes, for example,
Bug Bounty.
NOTE: CVS: Separate module for all docs, makes it easier to check out.
NOTE: Wiki is acting as a work-in-progress area to make process and
info available immediately. Eventually, all of this will be in
the Doc Guide.
NOTE: If ViewCVS doesn't provide the reporting we need to track
documentation activity, we can look into scraping
fedora-docs-commits into a Wiki. Objective is to use existing
tools to capture document status instead of having another Wiki
page for everyone to keep updated.
NOTE: A layout/outline using blank XML pages is considered enough to
get into CVS with.
NOTE: Snot is considered off-topic.
NOTE: It's nice to have a list of closed and accomplished tasks.
--
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
18 years, 10 months
research on using the GFDL
by Karsten Wade
Since we incorporated some text from the GNOME Documentation Style Guide
(GDSG), we need to update our Doc Guide to attribute the included
content covered under the GFDL.
Then we need to decide if we're forking. I think we are. We will have
to manually include patches from GDSG. The diff between the two guides
will be too great, and will go over time.
However, we need to capture immediately the bug fixes we made so we can
get them upstream, before they get lost and our reasoning gets stale.
Paul, can you dig out from SVN what you did previously? We'll add that
to the fixes I made and you made in cvs.fedora and split up the list to
file bug reports.
Now, on to the fun stuff ...
Today I read the GFDL again, read some opinions from debian-legal, and
did some thinking. Here is what I have so far.
http://www.gnu.org/licenses/fdl.txt
## We need to take an action to comply with this:
B. List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
## We need to create/modify History, with that title :/
I. Preserve the section Entitled "History", Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled "History" in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
## After some digging, here is one of those canonical pages:
http://developer.gnome.org/documents/style-guide/titlepage.html
## The whole thing with "Exactly Named Pages" is a little strange. The
## GDSG doesn't have a link from the ToC on index.html to
## titlepage.html.
## The following action is to make sure there is a page, on or linked
## from the "History" page, that tells how to get the source for the
## document.
J. Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the "History" section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
## We need to redo the organization a bit, I think we all like the way
## GNOME doc prefaces are laid out. We can start by creating a History
## etc. to fulfill licensing agreements.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the section all
the substance and tone of each of the contributor acknowledgements
and/or dedications given therein.
## Beginning to wonder if we need an appendix to cover some of this
## stuff ...
## Here is an important part that tells us exactly what we need to do in
## combining the documents, which is arguably what we did:
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled "History"
in the various original documents, forming one section Entitled
"History"; likewise combine any sections Entitled "Acknowledgements",
and any sections Entitled "Dedications". You must delete all sections
Entitled "Endorsements".
####################
One problem I am hearing about occurs if we include the
"Acknowledgements" or "Dedication" section, we may greatly reduce the
freedom of our document. In this matter I defer to the debian-legal
list for all the reasoning. Here is a page that appears to cover all
the details:
http://people.debian.org/~srivasta/Position_Statement.html
Because the GDSG doesn't include any Invariants or other immutable
content, we are fully free to use it. Similarly, our GFDL is nicely
fully free.
Anyway, I don't want to seek legal advice unless we can't find a clear
precedent of how to act. It's seeming clear, so far.
cheers - Karsten
--
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
18 years, 11 months
[RFC] dumping the CED in favor of local variables
by Karsten Wade
I'd like to recommend we dump the usage of CED files in favor of the
local variables designation. The CED file is a pre-compiled DTD subset.
http://fedora.redhat.com/participate/documentation-guide/s1-emacs-cedfile...
The only noticeable change that matters is that indenting is different
by two characters overall. It's really no big thing to reindent entire
files, or sections of them to avoid <screen> blocks.
The CED files technically need to be recompiled with the introduction of
each new tag. They are a hassle to load everytime you load the
document.
The local variables will load the parent file in the buffer, which is
convenient, and does all this automatically when you open the file.
You put one of these at the bottom of each XML file:
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
xml-parent-document:("parent-file.xml" "book" "chapter")
End:
-->
The small pain of converting our docs will be more than made up for in
the not-so-long run.
- Karsten
--
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
18 years, 11 months
Submitted Document Bugid: 156771
by Thomas Jones
Hello all,
As per a recent conversation, I have generated a patch for the general
entity file --- fedora-entities-en.xml.
https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=156771
There were a great many changes that I have made. Not all may be
accepted into CVS; but I believe that these changes provide good value
to the project.
As you review the changes, please keep the following "open" issues in mind:
- this file is incorrectly identified as xml. When in fact, it does not
contain any XML markup at all. Just a thought. In keeping with
standardization, it should be something like en.fedora.dbgenent.ent.
But, thats just personal preference. ;)
- if the "bluecurve" entity is accepted; does the <interfacedefinition/>
element suffice as the parent node with its expected context?
- if the "rpm" entity is accepted; what is its legal status? registered
or trademark?
- i neglected to utilize the common ISO entity declarations for
readability. New authors find it difficult to read if utilized; yet
translators probably need the ISO declarations. I prefer ISO --- but
then again i am weird. ;)
Hopefully, this will help.
Thomas
18 years, 11 months