Using elvis?

[Colin Charles]

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

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)

> > 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?

> 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

> 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 at 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