1:50 p.m.
Hi all,
I'm interested in working on one of the Fedora bounties, specifically the
'publishing man pages' project [1]. For those that might not know, the
project is to have an automated way to grab all the man and info pages from
a release and put them on the web to be searched and browsed online.
Extending that, putting the documentation into a wiki system is also
possible (and open some interesting opportunities, in my eyes).
I was wondering what some of the groups thoughts and goals of this project
might be. Both so that ideas can be brought out early, but also to know what
I might be getting myself into :)
So I pose the questions:
*Would you like to see man/info pages be online? (broken down by release
version, etc, or not)
*Would you want them in a wiki?
*What about pushing changes on the wiki back to the maintainers of the
respective packages?
*Would this be a welcome addition or just more work?
*What would you like to see this project accomplish in terms of Fedora
Documentation? (hopefully beyond just googling for a man page and having it
return a fedoraproject.org URL)
Cheers!
[1]
http://fedoraproject.org/wiki/FedoraBounties#head-f4affa8058dbc6a6b0568c3...
--
Michael Burns * Open Source Lab
Oregon State University
2:56 p.m.
On Thu, 2007-03-22 at 11:50 -0700, MBurns wrote:
Hi all,
I'm interested in working on one of the Fedora bounties, specifically
the 'publishing man pages' project [1]. For those that might not know,
the project is to have an automated way to grab all the man and info
pages from a release and put them on the web to be searched and
browsed online. Extending that, putting the documentation into a wiki
system is also possible (and open some interesting opportunities, in
my eyes).
I was wondering what some of the groups thoughts and goals of this
project might be. Both so that ideas can be brought out early, but
also to know what I might be getting myself into :)
Good idea. Having this discussion in the open makes sure we are all
working from a common ground.
So I pose the questions:
*Would you like to see man/info pages be online? (broken down by
release version, etc, or not)
Yes. Able to be indexed for a search.
*Would you want them in a wiki?
Depends. If we could make the Wiki accept changes and write them to the
real man page source, then it makes sense. That seems like a very hard
thing to accomplish. Maybe just a subset of the man/info pages, such as
the ones where Fedora is the upstream (anaconda, system-config-*, etc.).
Otherwise, I'm not sure it makes sense to put in a wiki. We could use
it as a way to accept edits/suggestions, but if we have to manually port
them to the man/info source ... well, we have to think if it is worth
it. If that is a role this project wants to take.
My sense is that we want to see improvements in the man/info pages, but
cannot take on too much work around it without an improvement in the
basic tools. Committing changes to TeX files in CVS does not sound like
an improvement. :)
*What about pushing changes on the wiki back to the maintainers of
the
respective packages?
Such as, have a mapping of content to who owns it? Then issue an email
that is a diff or a patch?
That's not a bad idea. It could get annoying, so maybe we need a way to
bundle up all the changes into one send, v. sending every time someone
saves a change to the wiki.
*Would this be a welcome addition or just more work?
As detailed above. If it is more work but gives a great benefit, we
should consider doing it.
*What would you like to see this project accomplish in terms of
Fedora
Documentation? (hopefully beyond just googling for a man page and
having it return a fedoraproject.org URL)
That is a really good question! This project is fairly old, so maybe
the motivations are lost in the mists of time.
I think this stretches waaaaaay back to an old Red Hat Docs Team goal of
converting all the man pages to a DocBook format, and then work on
improving them.
The main motivations I can think of are:
1. Provide useful, Fedora-specific content (man/info pages that only
appear in Fedora)
2. Make this content available in many ways (CLI, WUI, but if they were
XML, they could appear in GNOME Yelp or KDE Help)
3. Contribute fixes back upstream to improve the state of all content
It is the latter that is truly the most interesting ... and also the
hardest to accomplish.
- Karsten
--
Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project
Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject
quaid.108.redhat.com | gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
4 p.m.
On 3/22/07, Karsten Wade <kwade(a)redhat.com> wrote:
Good idea. Having this discussion in the open makes sure we are all
working from a common ground.
Absolutely. Thanks for replying!
Such as, have a mapping of content to who owns it? Then issue an email
that is a diff or a patch?
This was my thinking, yes.
That's not a bad idea. It could get annoying, so maybe we need a way to
bundle up all the changes into one send, v. sending every time
someone
saves a change to the wiki.
Two ways that jump out at me.
(1) Do a batch run. So N days before a release, we run a script that makes
one big diff per page and send it out to each respective maintainer.
(2) Have a Stable page version. So each change doesn't get a patch release,
but once we have a reviewer/editor approve a set of changes, they move the
Stable bit up to that version of the page.
I think this stretches waaaaaay back to an old Red Hat Docs Team goal of
converting all the man pages to a DocBook format, and then work on
improving them.
The main motivations I can think of are:
1. Provide useful, Fedora-specific content (man/info pages that only
appear in Fedora)
2. Make this content available in many ways (CLI, WUI, but if they were
XML, they could appear in GNOME Yelp or KDE Help)
3. Contribute fixes back upstream to improve the state of all content
It is the latter that is truly the most interesting ... and also the
hardest to accomplish.
#3 Is really my end goal, I think. First, get all the documentation into
some common format (DocBook, XML, a MySQL database), and then have some
facilities to export (and push changes) to various upstream and user
interfaces. Web, GUI, CLI, etc. The more the better, so long as they serve a
useful purpose.
Of course, this is a big project that most be broken down into various,
bite-sized steps.
--
Michael Burns * Security Student
NET * Oregon State University
6246
days inactive
6246
days old
2 comments
2 participants
participants (2)
-
Karsten Wade -
MBurns