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