On 11/25/06, Karsten Wade <kwade@redhat.com> wrote:
On Fri, 2006-11-24 at 22:09 +0300, John Babich wrote:

Yes, and as you have already imagined, many projects are in this first
step, and know it, and aren't sure how to move from there.

I'd suggest, or really second as this idea has already been put forth that we begin by opening channels of communication between us and others in similer endeavors.
 
 
If there is enough interest here to really get something of this
magnitude started, let's knock around all the tough stuff for a few
weeks.  I'd like to sponsor a teleconference + IRC + gobby +
$whiteboard-app mini-summit for all those who are interested in moving
this forward.  From today, it seems like January would be a good time;
give us about five to six weeks of mailing list activity and research
before getting together to hammer out a proposal to take to other FLOSS
projects.


That sounds like a good idea. Question of whether other projects are as interested in co-opertive efforts.  



This is interesting, the focus/inclusion of toolchain within this.  I'll
get back to that.

> This project is bigger than all of us. This is where we need to
> realize that the entire FOSS community needs to be involved. Every
> FOSS project needs documentation. It seems every project also has a
> problem producing it.

Documentation, coding and all other aspects. It's volenteers doing the work. So people as they are able and willing to produce bits and pieces, the weak spot of Open Source.  How can you set a deadline on somebody doing things purely out of good will?  They have to pay bills first. Many companies have generously donated the services of employees to work on OS  projects on company time. That has helped tremendously. I think that may be the best route. Companies that depend on OSS efforts can see the clear benifits in allowing people to work part time on OSS projects. Promoting this may be a way to give people more time for OSS projects.
 
1. There aren't as many commonalities between distros as there are
differences

I found that distros based on the Red Hat model like Mandriva, Knoppix, Cent OS and SUSE to have quite a bit in common and very little difference. I can sit down at a Mandriva machine and forget what distro I am on.  SUSE has noticable differences but most things run exactly like they do on Fedora. The tools vary some in the GUI. Especially for system maintenance. If you go to the configuration files they look almost exactly the same.

I havn't installed Ubuntu so I have little idea on the differences.  I installed the most recent Debian distro a few years back when my company was deciding on what distro to move too after Red Hat split into Enterprise and Fedora. There were some noticable differences in many areas but the core of it was just plain Linux like any other distro I've worked with. The big diffences were again in the GUI and system tools like package managers. I also tried out Free BSD, a Gentoo distro, SUSE, Mandriva and a couple less well known distros. Free BSD had the most differences obviously since it was not Linux. Still even between Linux and BSD there was a core feel that was easy to adapt too. Unlike Solaris which did some rather odd things in my opinion.  ls is ls, df is df. /etc was /etc while you might find a few things moved around the core of it stayed the same. The differences seemed to be things like tarball vrs rpm vrs apt-get and the many other variations on how to install an app.  The GUI or lack there of for configuring a file that is identical or nearly identical in various distros.

I think that a common documentation project would help bring the best of each distro to other distros. I wouldn't be surprised to see package managers like yum and apt-get agree on a common interface. The internals might be different but standardizing the interface for the best usability would make it easier for all.  Many GUI apps are distro independent. So while under the hood there are differences, to the end user the distro is transparent while using a tool like grip or the desktop itself whether it be Gnome or KDE or a lightweight window manger or while not running X at all. Apache is apache, MySQL is MySQL. The location might be different for the files but the files are the same and what you do with those apps and files are the same.
 

2. Any body that does this work is going to spend a significant amount
of time dealing with politics and in-fighting

That is the question. The politics and the my distro is better than your distro kind of thing. Another set of politics is old school Nix vrs new school Nix. That's a knot to resolve.

 

In the end, it might be the last one that is the true challenge.  People
like what they like and don't want to change over to what I like or what
you like.  If we don't want to make fixing the attitude of all

One of the beauties of Linux is the freedom of choice and the ability of each and every user to build a machine that fits them like a glove.  What is a great way of doing things for one person may be a horrible way of doing it for another. Lyx might be a great tool for some. Others will prefer to work in HTML based technologies.

The solution is simple. A standardized output format that allows people to use what tools suite them best in the creation then they merely export to the needed format or submit a common format to be converted to the standardized format.
 
I do have a problem with the Unix man page format myself. Most are about as useful as no documentation at all. Especially to newer users. The options are often not well explained and frequently missing options that have been added since the creation of the man page. A good man page has extensive examples, many man pages completely lack examples at all or only have examples of the most basic usage. I and many others turn to Google rather than man pages for the bulk of our documentation reference. There we find usage examples that can easily be modified to suite what we are trying to do. There are no man pages for most GUI apps, the help pages usually missing or very bare.

Most importantly, the idea of the info pages seems to have been really abandoned. The Info pages were an attempt to address organizing tools by tasks and giving users and alphabetical list to look through as well. I'd love to see an X version of info which had the kind of details you find in a X versions of Yum. Since I started using gnome-yum I've discovered dozens of really useful tools I have had on my machines for years but just didn't know about. Few people really realize the power of the software already on most Linux distros. I would suggest that as a format. Look at the way Gnome-yum organizes packages to download and the kind of descriptions you get. What if you could do the same thing with documentation?  Search, browse by catagories since many pieces of software will have multiple catagories and by various types of tags that can be applied such as X app, networking tool, sys admin tool, Windows connectivity software and so on. I think such a tool would be a help to long time and new Linux users alike.
3. Distro only.  We could start a new, cross-distro documentation
commons.  Maybe use an existing umbrella organization to work under, so
it can hold single control (joint copyright, etc.), sort of like an FSF
for documentation.  One issue that comes up immediately is license,
which is where the common upstream entity is valuable.  It can provide
multiple licenses for downstream use, who would have to multi-license (n
+1) all content they contributed back up.  Lots of complexity, and we
need to research the actual value.  For example, how much work would
this be v. putting human energy into converting all man pages to XML and
making a Web interface (Wiki) for editing them.  This cross-project
would be a lot of effort into interacting components.  The "Wiki in
front of man pages" would be putting content editing directly in the
control of the communities, and then we all just advertise
manpagecommons.org/wiki. :)

The easy way is to create it and let them come. If we created a tool like an X version of info that covered all aspects of Linux, then it would be fairly simple to attach distro specific flags to areas. To denote in common documentation variations between distros or if for example your sitting there at your desktop on a Fedora machine helping a Mandriva user you can switch to a Mandriva centric view of the documentation.  Each distro's documenation projects responsible for contributions to the project as a whole.