LinuxQuestions.org

LinuxQuestions.org (/questions/)
-   Slackware (https://www.linuxquestions.org/questions/slackware-14/)
-   -   Slackware Documentation Project (https://www.linuxquestions.org/questions/slackware-14/slackware-documentation-project-4175422561/)

kikinovak 08-17-2012 02:12 AM

Slackware Documentation Project
 
Hi,

I'm currently busy building my company's current "Enterprise Desktop" based on Slackware 13.37 and numerous addons coming mostly from SlackBuilds.org.

Back in 2006, I had to make my first "professional" use of Linux, since I was hired by the local town hall to install a complete computer network in eleven small to medium-size public libraries using Linux and free software. Back then, I spent quite some time with fellow slacker Daniel de Kok on a project we called "Slick": a full-blown Linux desktop based on Slackware, sporting Xfce and offering everything you need for daily work: office and multimedia and Internet stuff, and all the rough edges sanded down. If I remember correctly, we had about 200 extra packages for our custom desktop, and for the vast majority of these, we wrote the SlackBuild files ourselves. Unfortunately, we met some real showstoppers... like the fact that Slackware still defaulted to a 2.4 kernel at the time, so no HAL and no auto-mounting devices, and so I ended up using a beefed-up CentOS for the job (which is still used there, BTW).

And now I think of the difference between then and now. The SlackBuilds.org project has just made my admin life so much easier. For about 90 percent of the extra stuff I need, I just fire up sbopkg (which is a GREAT tool) and build whatever I need. Sometimes, I download a script and change it when I want to patch it or build a more recent version. Right now I have something like two hundred extra packages, and I only had to write my own SlackBuild scripts from scratch for about a dozen of them. So the SlackBuilds.org project has significantly changed my life, here.

Now I look out of the window (birds looping in the blue sky over the south French countryside) and imagine another project. Sometimes when I look at the documentation of some distributions like Arch or Gentoo or other projects like LFS and FreeBSD, I can't help thinking that's something that also makes a difference. Now I know there are already some great documentation efforts that have been made for Slackware, by Eric Hameleers, Daniel de Kok, Alan Hicks and other ones. There's the highly informative Slackbook (which I read on my honeymoon back in 2005, don't laugh), there are the Slackworld articles, and there's countless blogs scattered over the internet about how to configure a LAMP server on Slackware, how to use Dnsmasq, etcetera. I've taken quite some information from all these places. Eric Hameleers' wiki proved highly valuable for setting up a working Samba server, Daniel de Kok's Slackware book taught me how to use tagfiles, and so on. And now I imagine a project similar to the SlackBuilds.org project that would centralize all the available information for Slackware. It would work like the SlackBuilds.org project, the only difference being that folks wouldn't submit SlackBuild scripts, but articles about specific subjects ("How to build an initrd", "How to use MPlayer on the command-line", "How to configure 3D acceleration on an Intel video card", and so on). And like the SlackBuilds.org site is organized in categories, this site (slackdocs.org?) would also be organized in sections ("Package Management", "Multimedia", "Networking", and so on...) And like the SlackBuilds.org project, the site would be "run" by a staff of qualified volunteers, who would proofread, approve/reject, organize sections, etc.

What do you think?

PS: one first thing to do eventually would be to gather and organize the huge pile of existing information in the above mentioned places. The big idea behind this being: "OK, I need a piece of information, I'm gonna check slackdocs.org (or whatever) to see how it's done..."

Didier Spaier 08-17-2012 02:35 AM

I 110% agree.

In order not to reinvent the wheel, we could use Arch's wiki as a model - and maybe even steal them some content ;)

We could even gather from the maintainers of Arch's wiki some advises about how to start / work and content organization / do vs don't

EDIT Some time ago I posted on LQ Let's use the wiki more and better but got very few feedback. Anyhow your idea to have a specific Slackware Documentation Project is certainly better.

ruario 08-17-2012 02:59 AM

Quote:

Originally Posted by kikinovak (Post 4756405)
It would work like the SlackBuilds.org project, the only difference being that folks wouldn't submit SlackBuild scripts, but articles about specific subjects ("How to build an initrd", "How to use MPlayer on the command-line", "How to configure 3D acceleration on an Intel video card", and so on).

Isn't that just www.slackwiki.com? What stops you adding articles there?

Quote:

Originally Posted by Didier Spaier (Post 4756418)
Some time ago I posted on LQ Let's use the wiki more and better but got very few feedback. Anyhow your idea to have a specific Slackware Documentation Project is certainly better.

But you suggest LQ's wiki. Why not just use Slackwiki?

The only thing that stops the Slackwiki from being as good as the Arch wiki is people putting the effort in to do it. This might be because Slackware users are Slackers and can't be bothered ;). Perhaps they know how to get information from the various other sources (e.g. Arch Wiki) and don't see the need. Or maybe we are just a smaller community.

kikinovak 08-17-2012 03:05 AM

Quote:

Originally Posted by Didier Spaier (Post 4756418)
In order not to reinvent the wheel, we could use Arch's wiki as a model - and maybe even steal them some content ;)

Maybe it would not be a bad idea to somehow mimick the SlackBuilds.org layout, with a different color scheme maybe. If only to show the similarity in the approach.

The SlackBuilds.org folks are very picky for accepting a SlackBuild, which is essentially a good thing. The problem with too many wikis on the internet is the difference in quality for many articles (and I'm a bad advocate with my klutzy english, but I'm a german native speaker and I write mainly in french). If SlackDocs.org (let's call it like that in the meantime) intends to have high standards, there should be proofreaders both for the technical as well as the linguistic side. More often than not, an article can have very valuable technical content, but it's poorly written. In that case, a more gifted "writer" can complete the task.

More brainstorming anyone?

Didier Spaier 08-17-2012 03:18 AM

@ruario While you were posting I was asking myself the same questions ;)

I suggested LQ's wiki because it can be used for other distributions as well (I didn't post that in the Slackware forum).

There certainly is valuable content in Slackwiki, thanks to the contributors.

But I feel that it would benefit of a more structured organization and that Arch's wiki looks more attractive, though I may not be able to explain very clearly why I think so.

Another difference is there is a single URL from which Arch users can find pretty much everything they need, even if they are in fact redirected to other websites.

kikinovak 08-17-2012 03:28 AM

Quote:

Originally Posted by ruario (Post 4756439)
Isn't that just www.slackwiki.com? What stops you adding articles there?

There's lots of good information on SlackWiki. There's quite a lot of stale and outdated information there too. It's hard to tell, so everyone has to figure out himself if some piece of information actually works or not.

Plus, the information on the SlackWiki is organized in a "Wiki" manner, of course. Meaning when I go to the front page and I'm searching for some documentation, do I follow "Information" (I do look for information, yes) or "Tutorial" (well, maybe there's a tutorial for what I need) or do I look for "Tips" (yes, I need some tips about this specific subject)?

A few years ago I published a 500-page Linux bible (based on CentOS), and the first thing my editor asked me to do was write an abstract. Well, here's the link to the abstract: http://tinyurl.com/nhouby And the idea that follows: why not organize the Slackware Documentation Project in a similar fashion, with information being organized instead of articles from Asterisk to Zebra?

Another factor: the staff of editors I mentioned could ensure more or less easily that articles are up to date. Let me give you a practical example for this.

Let's say I contributed an article "How to setup a primary master DNS server using Bind". The article got reviewed and edited by the staff, and at each new release, someone in the staff checks if the information is still valid (OK, bad example, since Bind syntax won't change too much) and eventually ask me for an update. In the same way that on SlackBuilds.org, the mailing list is busy right now with updating the SlackBuilds for Slackware 14.0.

Plus, this centralized organization means avoiding duplicate efforts. I think the quality of the Arch and Gentoo documentation projects can be explained by the fact that they have an editorial staff dedicated to this task.

astrogeek 08-17-2012 03:39 AM

Maintain for different Slackware versions too!
 
I would be all in favor of this idea!

I think an important addition to the general Slackbuilds.org way of doing it would be to accept articles for older versions of Slackware as well, and index them by Slackware version.

Finding version-specific documentation is often as important and difficult as finding any documentation at all.

ruario 08-17-2012 03:42 AM

In my case, the problem is laziness or finding the time to add stuff to the Slackwiki. There is also the motivation aspect because in the back of my mind I sometimes wonder if it is needed. We don't have to duplicate efforts just for the sake of it. If the documentation exists but is hosted by another project, that doesn't stop you using it as long as it is good (generic) information. ;)

I used Arch before Slackware and hence am quite familiar with their Wiki. My past experience also means it is relatively easy for me to translate the few Archisms that exist. For that reason I can continue to use their Wiki for stuff I don't fully understand. Indeed the advice in most of the application specific articles works almost verbatim on Slackware (apart from using pacman rather than Slackware Pkgtools, obviously). The nice thing about Arch is that, like Slackware, it doesn't mess with its packages too much and does configuration via whatever method the upstream maintainer suggests, rather than some "fancy", all encompassing, GUI configuration monster^wapplication (yes I am looking at you YaST!).

Of course there are Slackware specific things I have had to learn along the way but these are covered in the admittedly scattered documentation sources (or they have been covered in questions on LQ). Sure it takes a little more searching but it seems like all the information you need is present if you look for it.

For these reasons, whilst part of me would love a Slackwiki that was on a par with the Archwiki, in all honesty I personally can't see myself contributing to it enough to get it there. :( Perhaps I might add (or edit) articles on Slackware specific stuff where there is a need and I know how to fulfil it but unless I suddenly have a lot of spare time I think that is the best I am ever likely to do.

Hopefully for your purposes the other Slackers out there aren't as Slack as me! ;)

Alien Bob 08-17-2012 03:47 AM

Remember that it takes people to setup and maintain a documentation source, but just having people is not enough. Vision, and determination is required as well or else you run the risk of creating yet another half-assed documentation site.

The success behind slackbuilds.org is that there is a small admin team which does the QA and approvals. That team has a vision about what the site should offer (and what not) and is determined not to let the quality and features slip.
The content is supplied by many people who are made aware that submitting a script at slackbuilds.org makes you also responsible for its being kept up to date. What you don't want to happen is people submitting content and then abandoning their submission. You end up with a lot of useless stuff.

The same can be applied to a documentation site (Wiki or otherwise).

Eric

ruario 08-17-2012 03:53 AM

Quote:

Originally Posted by kikinovak (Post 4756461)
A few years ago I published a 500-page Linux bible (based on CentOS), and the first thing my editor asked me to do was write an abstract. Well, here's the link to the abstract: http://tinyurl.com/nhouby And the idea that follows: why not organize the Slackware Documentation Project in a similar fashion, with information being organized instead of articles from Asterisk to Zebra?

Well you could make one page that links to the others in an organized fashion to solve this.

Personally I think that if people want this they should just start contributing to the Slackwiki. I don't think it needs that much discussion. Actions are more important than words. Perhaps I'm wrong but that is my gut feeling.

brianL 08-17-2012 05:39 AM

One thing for sure: there's nothing wrong with the written English of any of the contributors to this thread.

lolnameless 08-17-2012 07:32 AM

sorry i laughed :p
and one thing, am i the only guy who consider all wiki as a secondary,untrusted source?

IMO, a community forum or a practice to make good,complete tutorial on community forum is what we really want, that we can discuss anything against "the hive mind" casually, so we maintain a higher level of trust upon loose things like (how to use X the noob way, or X,Y and Z, which one is better)
In comparsion, such "style" trades the wiki style(the hyperlinked text) and a structure of catergories for casualty, the former is just convenience and the latter is essentially good imo.

Didier Spaier 08-17-2012 07:59 AM

Quote:

Originally Posted by lolnameless (Post 4756633)
am i the only guy who consider all wiki as a secondary,untrusted source?

I am not with you on that.

Be it collaborative or not - not all are - a wiki is nothing but a way of collecting, structuring and presenting information. This don't say anything about the quality of information.

In other words, I trust or not the writer, not the medium.

What kikinovak proposes, if I understand well, is to submit the articles to a peer review (sort of) before they be published. This is a sound proposal, IMHO.

Furthermore the information given in any media , once accurate, can become obsolete. This is especially true in fast evolving matters, like information technology.

So, it's up to everyone to think critically about what he or she reads or listen to, whatever it be.

sycamorex 08-17-2012 08:13 AM

I think the proposed model makes sense. A wiki format where a lot of contributors would submit their entries (to be approved by a few) will let the information stay more up to date and be reliable. The Slackbook being prepared by Alan Hicks may be a reliable source of information, but it doesn't get updated very often.

kikinovak 08-17-2012 08:29 AM

Quote:

Originally Posted by Didier Spaier (Post 4756661)
What kikinovak proposes, if I understand well, is to submit the articles to a peer review (sort of) before they be published. This is a sound proposal, IMHO.

Yes, that's the idea more or less. And since AlienBob speaks of necessary manpower: of course I would volunteer for many of the tasks involved. Organize sections, proofreading, translating my own documentation (for example the series of detailed articles about Slackware I published this year in "Plančte Linux").


All times are GMT -5. The time now is 04:43 AM.