On Wed, 2004-08-04 at 04:58, Colin Charles wrote:
On Fri, 2004-07-30 at 16:34, Karsten Wade wrote:
> > We've been talking about public CVS for far too long, and I think the
> > longer we wait, the longer Fedora Docs becomes less & less relevant
>
> Sorry if I'm being dense, but I don't understand how having public CVS
> resolves the problems of Fedora docs? I see a lack of content, some
> broken processes, and barriers to entry, but I don't see how public CVS
> resolves that.
People can commit to a place - it will be in one central location -
there will be drive and interest to write it
I think we are in agreement, at least on the major points:
1. A temporary CVS is useful, and Brad is generous to offer to setup and
maintain such.
2. Hosting Fedora docs not at
fedora.redhat.com/docs is fractious and
confusing.
Where do people who write Fedora docs now commit things to? Or host
it?
FedoraNEWS.ORG seems like a welcome host (but its not Fedora Docs!).
Random websites on the Net look like welcome hosts (but i ts not Fedora
Docs!)
We need docs in one place, not scattered all over the Net - we have to
grow as a project, and we don't have docs to start with (sending people
to RHL9 documentation is *embarassing*)
Lack of content is because there are broken processes and barriers to
entry. Stop telling people that there's Emacs, and only Emacs to use.
Let people write in HTML, and we might even find folk whom want to
DocBookify them - remember, together we stand and colloboration is the
way to get work done. Let's work like how FreeBSD/Gentoo get
documentation done (which is excellent, in comparison to ours)
That would make a wonderful bugzilla/RFE, to change our Doc Guide to say
that other formats are welcome _if_ the author gets on the list and
finds at least one person willing to help with the conversion.
I think that 50% of the HTML-based authors will get excited about
maintaining their own doc in DocBook. Perhaps part of the process of
maintaining a doc over the long term is to actually learn the toolchain.
But the toolchain need not be a barrier. And, as you say, if we have a
CVS to commit to, work will get done just because now there is somewhere
to put it. I'm sold on that idea.
> > Keeping in mind that the barrier of entry is already
relatively high
> > (you need to know DocBook, you need to use Emacs, etc...), this makes
> > folk move closer to creating docs on 3rd party sites
>
> Agreed about the difficulties. To address this, Mark Johnson mentioned
> the idea of doing a Fedora Docs Quick Start Guide. He would make it a
> focused tutorial, using his psgmlx mode for Emacs, which gives a
> friendly and useful XML editing environment. Would that be helpful?
I'm guessing. I can use Emacs, so this doesn't apply. Maybe we want to
ask fedora-list folk?
Some kind of Quick Start guide would be good, and it can have a short
chapter that tells you how to use other editors and toolchains, if they
will work.
Mainly, I think we should try to spend our energy on tools that work
under Fedora Core.
> Still, Emacs is not required, and there have been plenty of
offers to
> convert and actual conversions from just about any source document into
> a Fedora doc. The contribution of content is what is lacking.
Yes. Notice I've been picking out bits and pieces from fedora-list and
sending it to fedora-docs-list? I'll continue doing this...
But I'm willing to bet the lack of contribution is because the
momentum/wheel hasn't started rolling
Right. Out of these threads, I'm hoping we'll have the following:
* A bunch of bug reports on existing documents and websites
* Several specific lists of content that is ready to post on /docs
* Specific changes to make to /projects/docs
I'm in agreement with the rest of your points.
- Karsten
> Going back to the CVS, I don't see how giving write access
to people who
> are having difficulties learning the tools is helpful?
Give it to those that know how to use it. If say, 10 of us here have CVS
write access, we can get quite a lot of work done, I'm sure. Once there
are some actual Fedora Docs sitting online, at our documentation site
(not 3rd party sites, scattered, everywhere), we can definitely
encourage more to contribute
> OTOH, giving write access to some of the people who a) know the tools,
> and b) have demonstrated their ability to submit good code, that would
> be a great thing.
Not code, just documentation. If I see errors, it's easily fixable (and
I'm sure others who have write access will do it too)
> > Why can't we use
elvis.redhat.com ? Anaconda, translations and so on
> > happen at elvis, so why not fedora docs? This will mean external
> > contributors *can* commit to cvs as well
>
> This is an interesting end-run idea. Speaking for myself, my
> inclination is not to create a parallel system to what is being worked
> on and waited for.
We are actually using
elvis.redhat.com (my bad!). elvis==rhlinux. Its
just that we don't have commit access
Parallel system is more targetted towards source - I've not actually
heard much mention about supporting the docs project. I'm sure its part
of it, but its mighty silent
The longer we wait, the longer 3rd party sites will get stronger, making
this project more and more irrelevant
> My email about what content is actually ready for CVS and posting on
>
fedora.redhat.com/docs is very relevant to your question. Once we know
> exactly what there is to post and put in CVS, then we have something to
> agitate about. Deliver the content, and we'll find a way to get it
> posted.
I think there's content, and you've identified some. There's plenty
scattered on the Net (anaconda, davep has some, etc...), now the hard
task is getting it all in one place. Oh wait, we don't have this one
place :)
Don't get me wrong, I'm playing the Devil's Advocate here, but someone
has to do it. FC3 is going to be out within a couple of months, and we
have absolutely zero usable documentation. We should aim for a handbook
styled documentation, not point people to dated RHL9 docs
--
Colin Charles, byte(a)aeon.com.my
http://www.bytebot.net/
"First they ignore you, then they laugh at you, then they fight you,
then you win." -- Mohandas Gandhi
--
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41