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 SlackBook ,Ā slackbasics-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):
- 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
- 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)
- 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
- 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?
- 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
- 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):
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
very good initiative!
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…
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.
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!
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
I would not trust external services unless necessary. The most of the infrastructure which can be kept in trustworthy hands, the better.
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 :/
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.
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.
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.
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
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.
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
Could put the name of Slackware Linux as Slackware GNU/Linux!!
Hi Marcelo
The official name is “Slackware Linux” so that is what I am using,
Cheers, Eric
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
wow. Now we have to deliver!
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.
And how to add new language to the wiki?
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
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
Hi,
I think, MediaManager(Wiki) should be improved like this:
+ root
+ wiki/
+ images/
+ documents/
+ audio/
+ video/
+ other/
+ slackware/
+ images/
+ documents/
+ audio/
+ video/
+ other/
+ user/
…
Sorry for previous comment(spaces trimed).
+ root
+++++ wiki/
++++++++++ images/
++++++++++ documents/
++++++++++ audio/
++++++++++ video/
++++++++++ other/
+++++ slackware/
++++++++++ images/
++++++++++ documents/
++++++++++ audio/
++++++++++ video/
++++++++++ other/
+++++ user/
…
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!
Hi Ellendhel
Cool ! Looking forward to your contributions.
Cheers, Eric
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!