Main menu:

Sponsoring

Please consider a small donation:

 

Also appreciated: support me by clicking the ads (costs nothing) :-)

 

Or you can donate bitcoin:

 

Thanks to TekLinks in Birmingham, AL, for providing colocation and bandwidth.

Page Rank

Fame

FOSS Force Best Blog--2013 Award

Recent posts

Recent comments

About this blog

I am Eric Hameleers, and this is where I think out loud.
More about me.

Search

My Favourites

Slackware

Calendar

July 2014
M T W T F S S
« Jun    
 123456
78910111213
14151617181920
21222324252627
28293031  

RSS Alien's Slackware packages

RSS Alien's unofficial KDE Slackware packages

RSS Alien's multilib packages

Meta

Slackware documentation project

In a recently started thread at LinuxQuestions, a discussion is flourishing about what the community can do to provide Slackware users with an up-to-date set of documentation for the distro, much like a community site as slackbuilds.org provides up-to-date and high-quality SlackBuild scripts.

The Slackware documentation we currently have is generally of good quality (lots of it is part of the Slackware DVD) but it is scattered all over the internet in sites like the SlackBookslackbasics-i18n , SlackWiki , the LinuxQuestions wiki, and several small wiki’s and blogs maintained by volunteers. Having a centralized source of documentation much like the ArchWiki would be very beneficial to Slackware and its community.

The idea would be to start implementing a series of first steps (copied from one of my posts in the LQ thread):

  1. the wiki must be hosted somewhere with shell access to at least the admin team and with the possibility of managing a MySQL database as well as the apache webserver
  2. if that hosting costs money, some sponsor would have to be found since a monthly donation model will not work (look at all the sites asking for new money in order to survive)
  3. a team of site admins / editors would have to be assembled. The site admins do not necessarily have to be the editors – but we will need many more site editors than site admins
  4. the site must have a long-term purpose. The admins/editors will decide on that. Will the site be the definitive guide to Slackware? Will it replace the Slack Book? Do you want any affiliation with Slackware developers or will it be a 100% pure community effort? Will spin-off distros be covered and/or encouraged to participate?
  5. A high level structure of the Wiki will have to be erected ASAP. A style guide will have to be written so that the site will have a visual identity which permeates all articles. Think of article templates and a set of example pages as a demonstration of what a good article looks like
  6. decide on a license for the material. ArchWiki uses the GNU Free Documentation License, while I use the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported (CC BY-NC-SA 3.0) license for my own Wiki.

A post by Woodsman (an experienced documentalist) added further concepts for keeping the participation barrier low:

Rather than use a style guide approach, consider a simple check list for editorial helpers:

  • Focus on basic grammar, but let people write as they are able.
  • Eliminate slang and colloquialisms that non English readers likely will not understand.
  • Ensure all acronyms and jargon are explained with the first usage.
  • Use a “bite-size” approach: encourage contributors to use subheadings to reduce an article into smaller sections.
  • The goal of an editorial review is to help the writer, not hinder or control the writer.

Kikinovak already reserved the slackdocs.org domain while Patrick Volkerding kindly agreed to the use of docs.slackware.com if the site would want to be affiliated with the distro.

I went ahead and erected a Dokuwiki instance on my taper server – http://taper.alienbase.nl/dokuwiki/ .

That URL is now depracated. The wiki is using the new domain name (since 21 august):

http://docs.slackware.com/

It is open for anyone who registers an account there. After you register an account there (click on the “login” at the top right and follow instructions), you can get a feel of the dokuwiki syntax by creating new pages below the playground namespace, so as not to disturb the real wiki content. Just create a new page by replacing the second “playground” with a name of your own liking, such as http://taper.alienbase.nl/dokuwiki/playground:foo . The wiki will comment that the page does not exist yet and that you can click “create this page”.

A Dokuwiki site may or may not be the end product but it never hurts to start off with a bit of practicing. Note that the Wiki supports multiple languages. So, even though we would start with english articles, these could be translated and become part of the same Wiki.

I also registered the #slackdocs channel at Freenode for those who want to communicate more directly than through blog and forum postings.

Have fun! I really like feedback!

Eric

Comments

Comment from escaflown
Posted: August 18, 2012 at 14:35

very good initiative!

Comment from LoneStar
Posted: August 18, 2012 at 15:46

It’s not much of a contribution, but I want to say that I find the ArchWiki being a great source of detailed tech info for solving many system-related issues, easily applying to other distros like Slack. So if you follow that model I think it’s a good move…

Comment from Andrew Conway
Posted: August 18, 2012 at 19:25

This seems like an excellent idea. Unifying slackware’s documentation would be a great step forward. Woodman’s points are spot on – I wonder if he would be willing to perform some editorial duty himself?
I also agree that Arch’s wiki is a good example to draw ideas from. I can’t think of much else I would add, other than I would be a willing contributor to such an effort.

Comment from schultzter
Posted: August 18, 2012 at 19:33

I love the idea; and I’m already making a list of articles I’ll write or contribute too. Based on what I’ve done with my Slackware installations and the troubles I’ve overcome.

But I wonder if the hosting requirements are too steep? A domain name can be registered and managed for $10 a year; and pointed towards Google Apps for free (standard edition, at least). There wouldn’t be any apache or MySQL server to manage, which would reduce the administrator requirements and ease succession planning.

It might not be as fun to let Google (or Zoho, or ???) handle all the nitty-gritty background details. But if the objective is a wiki to document Slackware and the boring way gets us there but the fun way doesn’t then I’m all for boring!

Comment from alienbob
Posted: August 18, 2012 at 20:14

I would not trust a long-term documentation project to the free version of Google Apps…You also do not get a Wiki in Google apps.

Eric

Comment from BlackRider
Posted: August 18, 2012 at 20:30

I would not trust external services unless necessary. The most of the infrastructure which can be kept in trustworthy hands, the better.

Comment from red_fire
Posted: August 19, 2012 at 01:08

This is a great idea! I wanted to voice this out on LinuxQuestions awhile ago but I always found myself ending up on ArchWiki coz it does work with Slackware :/

Comment from Kingbeowulf
Posted: August 19, 2012 at 02:16

We can apply to a trusted sponser with data center, perhaps someone like http://osuosl.org/ , once we settle on a license. A dokuwiki might not be in the OSL perview or too small, but we can ask. There might be others that host Slackware mirrors as well that could host a wiki.

Also, I’ve used https://www.nearlyfreespeech.net/

For simple sites, dirt cheap and reliable AFAIK, ad hos some interesting features, like free sftp/ssh access.

Comment from weput
Posted: August 19, 2012 at 05:45

well
I have a vps that currently only runs my bynari mail server… (bynari is a company that does enhancements to kolab).

I could host the wiki there or on a shared host.

Comment from Niki Kovacs
Posted: August 19, 2012 at 16:47

Hi Eric,

I’m really grateful to see this idea begin to flourish. Thumbs up to your fast response in setting up a sandbox wiki space. I’m currently right in the middle of a job to finish for a client, which will take me until around the first week of september. Then I’ll gladly join you guys of the newborn Slackware Documentation Project.

Cheers from the hot South of France.

Comment from V. T. Eric Layton
Posted: August 19, 2012 at 21:47

Eric,

I would very much like to be a part of this. I have some Linux and Slackware skills, as you know, and quite a bit of grammar/punctuation skills. I maintain a few blogs, I’m admin/moderator on a few technical forums, I also run my own message boards.

Please keep us posted about this. If you need to contact me directly, my contact info in on my website.

Thanks! This is a GREAT idea! :)

~Eric AKA vtel57, Nocturnal Slacker

Comment from Eric Morrison
Posted: August 20, 2012 at 16:47

I would like to expand on woodsmans comments and suggest that all acronyms and jargon not only be defined at first use but also all successive uses be linked to either the first use or a dedicated stub. I really hate searching for definitions that the author assumes I know.

Comment from alienbob
Posted: August 20, 2012 at 22:42

Hi Eric

Actually, that is pretty easy to do with DokuWiki. It maintains an internal list of acronyms which can be expanded in a “local” list.
I’ll copy the last few lines of that existing acronym list for fun (it has 145 entries but I am sure that the lot of us can come up with more):

WAN Wide Area Network
WAP Wireless Access Protocol
WML Wireless Markup Language
WTF? What the f***
WWW World Wide Web
WYSIWYG What You See Is What You Get
XHTML Extensible HyperText Markup Language
XML Extensible Markup Language
XSD XML (Extensible Markup Language) Schema Definition
XSL Extensible Stylesheet Language
XSLT Extensible Stylesheet Language Transformations
XUL XML User Interface Language
YMMV Your mileage may vary

See https://raw.github.com/splitbrain/dokuwiki/master/conf/acronyms.conf

Eric

Comment from Marcelo
Posted: August 21, 2012 at 16:56

Could put the name of Slackware Linux as Slackware GNU/Linux!!

Comment from alienbob
Posted: August 21, 2012 at 19:03

Hi Marcelo

The official name is “Slackware Linux” so that is what I am using,

Cheers, Eric

Comment from alienbob
Posted: August 21, 2012 at 19:05

The site is now live under the URL http://docs.slackware.com/ thanks to Pat Volkerding’s change to the domain.

Old URL’s starting with http://taper.alienbase.nl/dokuwiki/ are automatically redirected.

Eric

Comment from escaflown
Posted: August 22, 2012 at 01:41

wow. Now we have to deliver!

Comment from Yousha
Posted: August 22, 2012 at 18:02

Hi,

What is Slackware official logo?

This:
http://slackbook.org/html/slackware_logo.png

or this:
http://slackware.com/grfx/shared/slackware_traditional_website_logo.png

Also why do not you any update Slackware.com subpages(faq, contact, support…)?

Regards.

Comment from Yousha
Posted: August 22, 2012 at 18:27

And how to add new language to the wiki?

Comment from alienbob
Posted: August 22, 2012 at 21:27

Hi Yousha

You just ask ;-)
I have added Farsi as another supported language to the Wiki.
I do notice that the monowiki template has a slight bit of problems with rtl (right to left) languiages – the toolboxes are not rendered properly.
I will look into that.

Cheers, Eric

Comment from alienbob
Posted: August 22, 2012 at 21:32

The official Slackware logo would of course be http://slackware.com/grfx/shared/slackware_traditional_website_logo.png

The graphic on slackbook.org is “fan art” just like about everything you find on http://www.slackware.com/~msimons/slackware/grfx/
The artwork I added to the wiki has been modified from the official logo as well – but I asked Pat’s permission first for using the modifications.

As for your other question about slackware.com sub-pages: I do not control or administer that server. We do have a test site (not public) where we are lokking into a new (off-the-shelf open source) CMS. That new site will have up to date information and the whole team should be able to post there.
Before you ask: that new site will _not_ go live soon. Slackware 14 has priority.

Eric

Comment from Yousha
Posted: August 23, 2012 at 12:12

Hi,

I think, MediaManager(Wiki) should be improved like this:

+ root
+ wiki/
+ images/
+ documents/
+ audio/
+ video/
+ other/
+ slackware/
+ images/
+ documents/
+ audio/
+ video/
+ other/
+ user/

Comment from Yousha
Posted: August 23, 2012 at 12:15

Sorry for previous comment(spaces trimed).

+ root
+++++ wiki/
++++++++++ images/
++++++++++ documents/
++++++++++ audio/
++++++++++ video/
++++++++++ other/
+++++ slackware/
++++++++++ images/
++++++++++ documents/
++++++++++ audio/
++++++++++ video/
++++++++++ other/
+++++ user/

Comment from Ellendhel
Posted: August 24, 2012 at 16:32

Hi,

That’s a very good idea! The fact is I just begin to wrote a French FAQ on the french-speaking community website (http://www.slackware-fr.org/) and I have various other documentations, I will try to add that in this new project.

Thanks a lot!

Comment from alienbob
Posted: August 24, 2012 at 19:08

Hi Ellendhel

Cool ! Looking forward to your contributions.

Cheers, Eric

Pingback from The Slackware Linux Documentation Project » Xoron Press | Xoron Press
Posted: August 26, 2012 at 05:22

[...] the original thread at LinuxQuestions.org – the Alien Pastures (Alien Bob’s blog) article – the Slackware Documentation Project wiki – the SlackDocs mailing list – IRC [...]

Comment from damgar
Posted: August 31, 2012 at 03:06

Congratulations on a good start. In briefly browsing the site, I didn’t see some of the great articles you have written such as your kernel building guide. I hope they will be included soon, I still reference it every time I build a new kernel! Again, congratulations, it looks like a fantastic start!

Write a comment