Using elvis?

[Karsten Wade]

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