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:


[attach]

[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.linuxforums.org/forum/slackware-linux/180886-lack-dependencies-dependency-resolution-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.

[attach]

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

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.