Community Documentation done right - Slackware's new 'doc' project.

[40hz]

If you've ever browsed the computer section of your local bookstore you've probably noticed the dearth (if not complete absence) of Linux titles. The relatively small demand for Linux information, as opposed to Windows or OSX, makes most big tech publishers reluctant to commit to printing large tomes about what is still a small part of the consumer computing world. And what little does make it to bookshelves is usually confined to one of the 'big three' distros (Ubuntu, Fedora, SUSE) along with an occasional book on one of the better known server-type Linuxes such as pfSense or Centos.

Some 'specialist' flavors of Linux like LFS, Arch and Gentoo have always had their own good quality docs available on their websites. But that's the been the exception to the rule for most distros.

One of the oldest (and still excellent IMO) Linux distributions is Patrick Volkerding's Slackware. Slackware was first released in 1993 and has continued through 13+ stable versions as of this day, making it the oldest still actively maintained distro in existence. Linux would not be where it is today without Slackware.

Because Slackware's 'product' philosophy differs from most other versions of Linux, it's gradually become less and less mainstream than those heavily funded and promoted distros such as Ubuntu and RedHat. Which is a shame. Because Slackware is a very modern, well-maintained, and carefully crafted version of Linux.

One of the biggest problems with Slackware (and Linux as a whole) is the general lack of comprehensive and easily found technical documentation. You can always Google and run down various information sources. There's usually a small doc collection to be found here, or a knowledgeable blogger there. But that's not the same as having an official "book" that's both easy to find and actively maintained.

Part of the problem is certain misguided individuals in the larger Nix community. These are the idiots who view having to dig for information as a necessary rite of passage to the nirvana that is Linux. The other part of the problem is that good technical documentation is hard to write and tedious to edit. With the end result being that the "docs" for a distro usually never get beyond the talking stage. (Note: even the big distros usually try to fluff it off with a small collection of how-tos and FAQs - and relegate all unpaid support requests to a volunteer-staffed help forum. Hardly an ideal solution for the average enduser.)

Slackware has recently decided to do something about that.

Enter "SlackDocs" the Slackware Linux Documentation Project:

Project Charter

Knowledge is power. Scattered and unfocused power is useless. To state it plainly, the vision and the ultimate goal of the Slackware Linux Documentation Project is to become the primary worldwide resource for all Slackware related information. This is a lofty goal, indeed. However, there is confidence that venerable Slackware Linux, the oldest actively maintained distribution of GNU/Linux, has the user base to accomplish this goal. You are invited to join and be a partner in this endeavor.

Who can help? Anyone can, from your uncle Ed who tinkers with Slackware on his old laptop to Linux gurus with development level skill sets. All are welcome. All can contribute something of value to this project. A wiki type resource such as this thrives on community. You've seen for yourselves what the GNU/Linux and Open Source communities have done in the past and are still doing today. Working together, the potential for success is greatly increased.

This project will need article submissions that run the entire gamut of Slackware knowledge. There will be a need for serious technical articles on hardware control, software applications, Slackware Linux implementations in business and personal computing, system administration, etc. Articles will also be needed from the every day Slacker on topics ranging from simple howtos to complicated resolutions and workarounds.

Submitted articles, as with most wiki type resources, will be peer reviewed. Corrections may be needed, amendments added, and so forth. No article should be deemed unimportant. If it has relevance to Slackware Linux and will assist someone somewhere to better utilize this operating system, then it is a worthwhile article. What is being done here is being done for others. This is an archive of knowledge being built for the future. Your participation will be the mortar that holds the bricks in place.

In order to fulfill the goals of this project, a reliance on civil discourse and the presence of a strong spirit of cooperation will be necessary. The rules here are simple. Be kind and considerate in your dealings with others. This project is not about individuals. It's about a community sharing and working together toward a goal. Your ego will not be a part of the Slackware Linux Documentation Project. Please leave it in the coat closet by the front door before you login.

That is the our contract with one another and with the future.

Many times, projects such as these start with good intentions only to 'peter out' once the initial blush of enthusiasm wears off. In the case of the Slackware however, there's far less chance of that happening because there's an already a well-maintained knowledgebase that's been running for years courtesy of Slackware loyalist Eric Hamleers. Eric has been chartered to bring the new doc project to fruition. And looking at the charter page on the new wiki, it seems he has a very clear idea of how this project needs to operate in order to be a success. It's worth a read by anybody who is doing (or planning) any sort of community project. Everything is clearly spelled out and made completely transparent, including an explanation as to why DocuWiki was selected for the project site.

One of the most interesting things is how they plan to get around the problem with most online-only wiki-based documentation: downloadable daily snapshots:

The choice for DokuWiki was made for several reasons; its syntax makes it more suitable for writing documentation as opposed to MediaWiki, which is more general-purpose. Also, DokuWiki is self-contained in a single directory and does not require an SQL database, which makes it highly portable (the intention is to make a “daily snapshot” tarball available for download once the Wiki foundation is complete).

All in all, a very nice move in the right direction. Let's wish them well!

[Paul Keith]

It's good news but I couldn't spot where the community documentation done right part is.

In fact, in that main page alone there's 5 links under the Getting Started section with at least 2-3 links being better off not being there.

Are the improvements more from a behind scenes improvement such as backups?

I admit I did skim it though and ignore most of the section on artwork and sidebars and this reads contradictory to my eyes:

[Not implemented yet] Our goal is to give you total creative freedom when writing content for the Wiki. But for the sake of quality assurance, we ask you to co-operate with one of our editors.

I'm sure they are planning some exciting changes but I just couldn't figure out. Can anyone spell it out?

[40hz]

The bigger part is a call to the Slackware community to get more involved. They want to expand the resource base from it's current small how-to/FAQ format to a full-scale info resource for Slackware. That would include application how-tos, projects, etc.

Regarding total creative freedom, I don't see how some responsible editing and 'QC' flies in the face of that. I see it more as "write and give what you will" but not with the automatic assumption that everything you send over, no matter what, will hit the wiki as-is. Please note too that this isn't so much a "tool for conviviality" as it is a tech documentation project. Philosophical and procedural discussions and debates are better left to the forums and irc channels. And Slackware already has plenty of those.

Tech documentation does not that often come down to things that are purely a matter of opinion. At least not usable tech documentation. There are, in fact, correct answers when it comes to many, if not most, technical questions. And there are usually optimal (or at least better ways) to accomplish certain things which most people who are knowledgeable in a given technical subject will agree on. Articulation and awareness of "best practices" and a "common body of knowledge" are usually what characterise good technical docs.

I think right now the front page is a bit of a hodgepodge because the project has yet to get into full swing. So it's currently providing what's available - which is essentially the old docs. The larger goal will be to pull that hodge together into a more streamlined and organised wiki as additional resources and articles become available.
 

[Paul Keith]

It used to be much clearer back in the day but nowadays there are wiki (each with their own sub-rule on what QC is), Quora-like systems, notifications and there are some portal-type websites like Mint which functions differently from a wiki but is part Yahoo Answers/Part How To manual/Part forum but is not really the forum but because of that has much easier random info for non power-users albeit there's only a few users really contributing to it.

I really hope this turns out well and doesn't just become an equivalent clone of the Arch Linux wiki which is great but Linux's right documentation tends to be written toward the reading audience who don't need to read most of the tech documentations like the beginner's guide sections.

[40hz]

^It will be interesting to see how it plays out. I started with Slackware. Mainly because it was the only thing available that a neophyte would have a chance of getting to work when I first started out. The Slackware community has always IMO been newuser friendly although, like any Linux community, they didn't suffer fools gladly - or put up with the crazies all that much. They were, however, more patient than most when it came to helping people who were legitimately confused - as long as they were willing to learn and not expect somebody to just come in and "do" for them.

Regarding Arch, I think it's an entirely different situation in that Arch is much like LFS or Gentoo. There is no intermediate or journeyman level in those distros. You're either a rank beginner struggling to keep up - or you're an expert user. It's just the nature of the beast. And different environments call for different documentation standards and practices.

From what I've seen (and experienced) it takes the average person about a full year (plus several reinstalls since they will seriously break things) before they'll get comfortable enough to use Arch or Gentoo as easily as they would something like Mint. But that's because Mint handles all the heavy lifting and behind the scenes shenanigans for you right out of the box.
 

[Edvard]

I too, started out with Slackware and used to be a big fan, but figuring out dependencies manually just to run something that didn't come on the ISO didn't sit too well with me (or my lovely wife) after a while.
Tools like slapt-get and swaret offered a lot of promise, but that's about it.
The typical response of Slackware users to the subject of automatic dependency resolution may be sound on a technical level, but is hell when you just need the thing to go and don't have the time to put into it.
http://www.linuxforu...ution-slackware.html

That said, glad to see the Slack community pick up the ball on documentation.  Looking forward to some quality contributions from that crowd.

[40hz]

FWIW I sometimes think the need to occasionally resolve software dependencies on your own has the hidden advantage of discouraging too much willy-nilly installation of software.

One problem with the distro repositories (and new software managers) is that it's often like turning a glucose addict loose in a jellybean factory. ("OMG! Just look at all this neat stuff! And it's all FREE!!! Hmm...now THAT looks cool. I wonder what it does?") And sometimes Linux's emphasis on freedom and the constant encouragement to "experiment" backfires.

I wish I had a nickel for every Linux newbie who installed something like Ubuntu and really liked what they saw, who then went hog wild installing everything that looked even remotely interesting (including adding PPAs to their soft sources without fully understanding the risks) and soon wound up with either a dodgy or totally 'pooched' system.

Very often, these same people will then remove Linux from their machines, and begin posting everywhere they can about how "stupid" and "broken" and "bug-ridden" and "not ready for the desktop" Linux is.

Too bad they conveniently forget how you can also bring a Windows machine to its knees by getting a little too crazy installing as much freeware as you can get your hands on.

I had a client who was a freeware/demo junkie. About twice a year he totally roached his main machine doing that and called us to fix it. Last time out I counted 14 different file managers, four defrag utilities, five different antivirus/antil-malwar utilities (three of which had scanners simultaneously active!), three different sync tools (also all simultaneously active), at least a dozen photo editors, god knows how many games, plus a bunch of other things too numerous to count (fonts) or too weird to be worth even looking at.

This guy was frustrated because his machine took something like seven minutes to get to the desktop on a reboot besides regularly freezing up on him once it did. (I myself was amazed he could get that poor little PC to boot at all.)

Oh yeah, he was also a regular user and firm advocate of registry 'fixing' and system tweaking utilities.

This is the same guy who was always protesting how software companies "must take their customers for idiots" and "treated them like children." Not that he really wanted to learn anything. He was of the "these things should just work by now" school of thought.



People like that make me want to scream sometimes. (Although two visits per year at full onsite rate did go a long way towards easing my pain. )

On the other hand, the people who make me want to scream almost all the time are the ones who conveniently forget how dumbed-down Microsoft and Apple try to make their whole "user experience." Supposedly it's done in the name of "convenience" and "user-friendliness." However, a good part of their motivation is also to foster enduser dependence and platform lock-in.

Not to say Linux doesn't have its own problems. But stupid is as stupid does. And nobody (or at least not anybody born on Earth to human parents) comes into this world knowing how to use this stuff. (Not even OSX - despite what Steven Jobs may have thought.) There is always a learning curve involved. Even if it's so ingrained that, by the time they're 12, most people forgot just how much they did have to learn in order to use Windows.

So why should Linux be any different?  

[Renegade]

I think it will be interesting to check back in a while and see how the doc project goes.

Large documentation projects are far from trivial. I've worked on quite a few. (If you develop any software for Samsung devices, chances are a good portion of what you've read has been across my desk - emails and other materials included.)

I do like the idea of a nightly build for docs. I loathe purely online documentation. "No, I do not want to visit your web site for information that should have been included with the product..." The nightly build for docs will be a big plus.

[40hz]

I do like the idea of a nightly build for docs. I loathe purely online documentation. "No, I do not want to visit your web site for information that should have been included with the product..." The nightly build for docs will be a big plus.

-Renegade (September 15, 2012, 12:56 PM)

Agree. I can't stand online-only docs.

If nothing else, I hope that particular idea catches on more broadly regardless of the success or failure of Slackware's doc project. Especially since it's something that can be automated.

It sure beats having site visitors using something like HTTrack to try and get an offline copy of your wiki or doc pages.

[Edvard]

FWIW I sometimes think the need to occasionally resolve software dependencies on your own has the hidden advantage of discouraging too much willy-nilly installation of software.

Trust me, I feel you there, and although I must admit I have my fair share of cruft from useful things I installed and forgot about 3 days later, things that aren't immediately useful or promising usually get the curb in less than 10 minutes.

I have not-too-fond memories of trying to install Sodipodi (FFS... SODIPODI!!) and taking 2.5 hours running it from terminal, seeing what it complained was missing, searching the internet for what package libonedamnthingafteranother-0.1.95-i386.0.so came in, installing it, running Sodipodi from terminal to see if it complained... ad nauseum.
Then I had the brilliant idea to try and install a game for my son...
Tuxkart, I believe it was (FFS... TUXKART!!).  Never again.

I totally understand the rationale and logic behind keeping things as non-automagic as possible, but I must admit I just don't have the time.  When the solution to a successful compile of an interesting source-only thingamajig is a simple 'apt-get install libwatchamacallit-dev' away, I can't imagine ever going back.