Minutes FDSCo 20 Sep 2005
by Karsten Wade
FDSCo meeting
20 September 2005
irc.freenode.net, #fedora-docs
Canonical schedule and tasks:
http://fedoraproject.org/wiki/DocsProject/FedoraDocsSchedule
Summary of Updates and New Tasks:
=================================
* http://fedoraproject.org/wiki/DocsProject/Tasks explains a useful and
preferred way for tracking FDP tasks.
* FDP continues to pursue a toolchain that is both 100% free and in line
with what the upstream DocBook developers are using. Tommy will
continue his pursuit of help in getting Saxon and FOP compiled with gcj
by going to an external list, docbook-apps. Surely someone somewhere is
working on this, too.
* Karsten is trying to get the final word on what translation process we
are using for FC5 test1. Expect it to all happen manually
through /doc/cvs, confirming that expectation with Sarah and Bernd.
* Lots of recruiting going on for beat writers this week. Looking
within the developers to supply and wrangle content.
* Trying to create some process to make the Wiki -> FDP DocBook easier,
look for Stuart's email showing MoinMoin -> XML output.
That's as far down the list as we made today!
Attending:
==========
Gavin Henry (G2)
Tammy Fox (tcf)
Karsten Wade (quaid)
Tommy Reynolds (megacoder)
Stuart Elliss (elliss)
Paul Frields (stickster)
Regrets:
========
Mark Johnson (mrj)
## 30 ##
--
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, 7 months
relnotes content list
by Karsten Wade
This new list receives all the content that flows into
relnotes(a)fedoraproject.org:
http://www.redhat.com/mailman/listinfo/fedora-relnotes-content
I've asked Elliot to point relnotes@ to this address only. All other
individual addresses are going to be dropped from that alias.
Everyone who has already chosen to be a beat writer or otherwise needs
this content flow is about to be subscribed by me to that list. I'm not
including FDSCo members who have not signed up for a beat, as per my
promise to start with a clean slate for this release.
This list is likely going to start slow, but in the future it may be a
great source for early, raw content that has other values to you. Feel
free to join the list just to watch it grow.
- 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, 7 months
Self-Introduction: Scott Glaser
by Scott Glaser
Full legal name (as you use it is fine)
Scott Glaser
* Virginia Beach, VA, USA
* Senior Engineer
* Lockheed Marting
* Your goals in the Fedora Project
* What do you want to write about?
* Just about anything that will make Fedora
easier to understand for a New Users.
* What other documentation do you want to see published?
* That is hard to say, first I would like to
assist in making the Fedora Core 4 Installation
Guide a document that will help new users in
installing Fedora Core with little or no
assistance no mater what method of install
they choose.
* Do you want to edit for grammar/writing and/or technical
accuracy?
* I am willing to help the group in any way I can.
* Historical qualifications
* What other projects or writing have you worked on in the
past?
* I have done a bit of technical writing while an
employee at Lockheed Martin. Mainly test
procedures, but lately I have had to generate
and edit some Linux/Networking training
lessons and presentations as non-programmer
I think the Documentation Project is a
perfect fit for me as a way to contribute.
* What level and type of computer skills do you have?
* I am an electronics specialist that has learned
how to use computers as part of my work. I am
currently preparing to return to school as I
realize that I still have a lot to learn about
computers. I have a vast general knowledge in
various computer platforms from PC to VME
and have worked with just about every OS that is
currently available.
* What other skills do you have that might be applicable?
User interface design, other so-called soft skills
(people skills), programming, etc.
* Being an employee of a major defense
contractor I have numerous skills that
may be of benefit. As I work with the US
Navy I am pretty good a taking technical
data and making it easier for the end-user
to understand. I would say that I am pretty
good at generating how-to documents.
* What makes you an excellent match for the project?
* I guess what makes me an excellent match for
the project is the fact that I really enjoy
helping people learn how to use Linux. I
started with Redhat 6.x and have not turned
back.
* GPG KEYID and fingerprint
pub 1024D/599000BD 2005-09-17 [expires: 2006-09-17]
Key fingerprint = 61F5 C7DF 2F63 4A53 44D2 B9BE 3841 EA4F 5990 00BD
uid Scott Glaser (Sonar_Guy) <sonar_guy(a)c-ccom.com>
sub 2048g/A6676129 2005-09-17 [expires: 2006-09-17]
--
Scott Glaser
Fedora Core User
Web - http://members.cox.net/sonar_guy/
18 years, 7 months
A few nice bits in CVS
by Paul W. Frields
While I was on and in various planes and hotel rooms in Seattle I
managed to cobble together a couple kibbles 'n' bits in the docs-common
module that should make our documentation easier to read.
One of the common complaints was that the revision history block on the
title page made readers wade through a lot of material in which they
weren't interested just to get to the real narrative. The revision
history now is linked in the same manner as the legal notice, so people
can get right to the table of contents as expected. (You can see the
results in the "yum" and "jargon-buster" documents on the
fedora.redhat.com web site now.) If you generate a "nochunks" version
of the HTML, the revision history appears inline, just as the legal
notice does.
One tiny drawback is that the build process (i.e. "make") issues a
warning about context. It's only a warning and does not affect the
efficacy of the build. I'm sure this is a small problem easily fixed by
someone who understands XSL better than I. That someone might even find
a better way to accomplish the task, and if so, please have at it.
In the meantime, if you have a docs-common/ module checked out of CVS,
you should update it ("cvs up") now. If you have no idea what I'm
talking about, then you need to speak up on the list so we can answer
any of your questions and get you working on some of the good stuff! ;-)
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
18 years, 7 months
Wha' happened?
by Paul W. Frields
Why do none of my documents now clean or build using the standard "make
clean" or "make"/"make html" commands? I notice the Makefile.common in
docs-common changed yesterday. Hints please?
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
18 years, 7 months
[ANN] New support for document translations
by Tommy Reynolds
Hello!
The Fedora Docs Steering Committee has been discussing the best way
to add support for multiple languages in the FDP material. The
decision has been made to have the English and non-English
translations to be in peer files:
mydoc-en.xml
mydoc-de.xml
and so on. Translators will provide a complete mydoc-<locale>.xml
file that we will just drop into the document directory.
I have updated the FDP document building infrastructure to accomodate
this. Now, a simple make(1) command will build any or all forms of
the document (separate HTML files, a single HTML file, a PDF, or a
tarball) for each supported language.
The example-tutorial document has been updated for the new technique.
Please review it before making changes to your own document.
Most of the make-fu is in the "../docs-common/Makefile.common" file
where it belongs. While you are welcome to browse it, you don't really
need to be concerned with it unless you are curious.
The per-document "Makefile" has gotten simpler. Only 3 lines are
needed:
LANGUAGES = en
DOCBASE = example-tutorial
XMLEXTRAFILES-en =
should do the trick for an English file. After adding a German
translation, the "Makefile" would look like this:
LANGUAGES = de en
DOCBASE = example-tutorial
XMLEXTRAFILES-de =
XMLEXTRAFILES-en =
Note:
All output files will be rendered using UTF-8 encoding for
all of the locales defined in the ${LANGUAGES} macro. So,
if you need a more precise locale, use something like:
LANGUAGES = en_US en_GB
and name your files "mydoc-en_US.xml" and "mydoc-en_GB.xml".
As always, if you have trials and tribulations, or you just want to
ask, do so on this list so that everyone may benefit.
Cheers!
18 years, 7 months
XML style guide
by Karsten Wade
Mark Johnson and I are working on an update to the DocBook XML style
guidelines. These are currently mixed between the Fedora Documentation
Guide[1] and the example-tutorial in CVS.
Our objective is to make a complete, unified, canonical, and community-
influenced set of style guidelines.
Our other objective is to use these guidelines internally. One of the
interesting effects of having a good toolchain and documentation about
how-to document is that FDP is being used by people for internal or
other non-Fedora documentation needs.
I think that is *so* cool.
Open source content is more than just technical talk. It includes
marketing talk, project management talk, process talk, style, usability,
and design talk, philosophy talk ... well, that last one is at the core
of the free software movement, an open, conversant philosophy.
Anyway ...
You are watching this DocBook XML style guidelines unfold in front of
you on this mailing list, with your participation encouraged.
Thanks - Karsten
[1] http://fedora.redhat.com/participate/documentation-guide/
--
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, 7 months
Release Notes - A New Era
by Karsten Wade
It's time to start gathering notes for FC5 test1 and final release
notes.
There are some very good changes and additions to the process, to make
participation easier. There are also some new things that you, as
developers, must do.
Highlights:
* Wiki used to gather notes,
- not just bugzilla!
* Using *docs* keyword in CVS commit logs
- new magic from Elliot!
* Translations of relnotes included in fedora-release package
* Sub-projects responsible for supplying a beat writer
- You can coerce them, you can hijack them, but you have
no content in the relnotes without them
http://fedoraproject.org/wiki/Docs/Beats/HowTo covers much of this same
material.
Don't know what the relnotes beats are?
http://fedoraproject.org/wiki/DocsProject/ReleaseNotes/Beats
* Changes *
** Wiki Used to Gather Notes **
Beat writers are now able to use the tree at
http://fedoraproject.org/wiki/Docs/Beats to gather raw input and form it
into content for the release notes.
These pages have a light structure that generally goes one layer deep,
for example, Docs/Beats/Kernel is for the kernel portion of the release
notes. This maps nicely to one <section> or <chapter> in XML.
Beat writers are free to add and change sub-pages, as they need. Other
contributors can do the same. The only requirement to edit is that the
user be registered and logged in.
These beat notes are ongoing workspaces. A snapshot is taken just prior
to freeze for translation, and the content is merged into the overall
DocBook/XML-based release notes. These XML release notes are canonical,
but necessarily behind the raw Wiki pages.
Beat writers need to keep the content cleaned-up and relevant. You want
to watch your page and all sub-pages using the pattern
Docs/Beats/Beatname.* in your "Subscribed wiki pages" of your
UserPreferences.
Wiki-help for beat contributions is on-topic for #fedora-docs.
** Highlighting Your CVS Commit for Documentation **
The next time that you make a CVS commit that fulfills a feature, fixes
a bug, or otherwise is worth noting in the relnotes, try this trick.
Put the keyword *docs* in the commit log message, and a copy of the
commit is sent to relnotes(a)fedoraproject.org . The beat writers and
editors parse the note into the proper place, or open a bugzilla report
to track the note suggestion.
This is a must-do for Core packages, look for opportunities. Extras
packages are encouraged to use this at milestone events, etc.
This page tells more about what to highlight for *docs*:
http://fedoraproject.org/wiki/DocsProject/WhatToDocument
** Use Bugzilla to Highlight an Existing Report **
Just add relnotes(a)fedoraproject.org to the Cc: field. We'll parse this
into the proper place.
** File a Bug Report **
This small URL is for a pre-filled bugzilla report. This is a great way
to submit a note or idea for the release notes, since conversations and
solutions are logged. Bugs are set to block a master tracker for the
release.
http://tinyurl.com/89dkk
** Translations With Release **
The schedule for the release notes now includes time for translation, so
that the translated content can appear within the fedora-release
package.
At the top of the shipping release notes is a prominent link to the
latest online version of the relnotes. This helps to counter the
problem of having to freeze the release notes so long before test and
release. We'll do a Web-launch of a latest set of release notes to time
with the distro releases.
* New For Developers *
You are responsible within your Fedora sub-project to produce content
for the FC release notes.
Someone from your team needs to step-up and take the role of beat
writer, or find someone interested in helping your project to take that
role.
Being a beat writer is a _fantastic_ and reasonable way to get involved
with an open source project. It's designed to be bite-sized for the
average volunteer.
Ultimately, the amount and quality of content in the release notes is
your responsibility.
The FDP takes all the rest of the responsibility -- merge, edit, convert
to XML, get translated, build multiple output formats, package for
fedora-release, publish to Web, make downloads available, and support
with ongoing updates as needed.
** Deadline to Pick Beat Writer **
By 23 September, all sub-projects need to have picked the person who is
the beat writer for your part of the release notes. This is effective
for FC5 and forward. In other words, a beat may be handed-off, it may
not be abandoned.
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, 7 months
Minutes for 13 Sep 2005 meeting
by Karsten Wade
FDSCo Meeting
13 September 2005
Attendees:
==========
Gavin Henry (G2)
Tammy Fox (tcf)
Karsten Wade (quaid)
Tommy Reynolds (MegaCoder)
Stuart Elliss (elliss)
Mark Jonson (mrj)
Guests:
=======
Rahul Sundaram (mether)
Regrets:
========
Paul Frields
Updates:
========
* New release notes beat writers are being recruited. Tools now
include the Wiki, which we hopes greatly increases participation.
* Meeting is trying to use the Wiki schedule at
http://fedoraproject.org/wiki/DocsProject/FedoraDocsSchedule as the
agenda. This is the practive of other project committees. Worked
pretty well. List is now canonical for all FDSCo tasks.
* http://fedoraproject.org/wiki/DocsProject/Tasks is the page that
describes how tasks are managed.
http://fedoraproject.org/wiki/DocsProject/MasterTasks is deprecated
* We need help with getting FOP and Saxon compiled with gcj
* Staging server to provide Docs Rawhide is in the works. This will
provide builds of all versions of a document, publishing fixed URLs
of the output that includes HTML, tarball, PDF (where possible), and
all available languages.
* Details about translation for FC5 release notes and docs are being
worked. Tommy will modify the Makefile to make it i18n'ized.
* Keyword for CVS commit logs is fixed at *docs* and will be announced
ASAP.
* Karsten to make first relnotes announcement, to include details of
how new process works.
## 30 ##
--
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, 7 months
Java developer needed to help with Fedora Docs Project infrastructure
by Tommy Reynolds
Hi, All!
Over at the Fedora Docs Project, we have a problem that we think you
can help with. Our developers use XML DocBook so that we can
generate both HTML and PDF forms of the document from the same
originals. The HTML generation works great, but the PDF generation
is broken.
Our current tool "xmlto" uses TeX to render to PDF, but that hasn't
been maintained for a long time. We can use Apache FOP for the
rendering but don't want to use the JVM version because it doesn't
have an open license.
So, here is how you could help. We'd first like to get Apache FOP
native compiled using gcj and then maybe add in some open-source PNG
or JPG rendering libraries.
If you would like to help, you can reply on this list or contact me
privately at:
Tommy.Reynolds(a)MegaCoder.com
I look forward to hearing from you!
18 years, 7 months