LinuxQuestions.org
Review your favorite Linux distribution.
Go Back   LinuxQuestions.org > Forums > Linux Forums > Linux - Distributions > Slackware
User Name
Password
Slackware This Forum is for the discussion of Slackware Linux.

Notices

Reply
 
Search this Thread
Old 08-17-2012, 08:34 AM   #16
Alien Bob
Slackware Contributor
 
Registered: Sep 2005
Location: Eindhoven, The Netherlands
Distribution: Slackware
Posts: 5,184

Rep: Reputation: Disabled

I think Wikis are the best technology to create a community-driven documentation project. See Arch Linux and (in the past) Gentoo.
I chose Dokuwiki instead of mediawiki for my own documentation site, because it has better syntax elements for producing good documentation, it has a good visual editor out of the box, it has a proper ACL structure (whereas mediawiki is an "everybody is equal" wiki) and can be expanded with plugins and skins.

I do not think we will ever see a new version of the SlackBook, considering what I said in my previous post (without dedication and group interaction, progress will come to a halt) so a real community documentation project would be very welcome. The SlackWiki is not getting all that much attention (look at how the slackwiki.org domain expired) and I put more time into my blog than into my Wiki. A few "moderators" will have to step up and construct a Wiki page framework - perhaps using the chapter structure of the SlackBook and extending that. I would certainly transfer some of my documentation (and create new pages) to such a Wiki if I trusted that the moderator team was dedicated has fresh ideas.

Eric
 
Old 08-17-2012, 08:35 AM   #17
kikinovak
Senior Member
 
Registered: Jun 2011
Location: Montpezat (South France)
Distribution: Slackware, Slackware64
Posts: 1,489

Original Poster
Rep: Reputation: 662Reputation: 662Reputation: 662Reputation: 662Reputation: 662Reputation: 662
Quote:
Originally Posted by sycamorex View Post
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.
The only problem with a wiki is that it's a bit ugly, to be honest. Of course, "les goûts et les couleurs ne se discutent pas" (meaning you don't discuss taste and color), but imagine this: visit SlackBuilds.org, go to the "Repository" page. Imagine a similar site "SlackDocs.org". Imagine you are facing the task of setting up some centralized authentication for a SOHO network... so you would simply click on the "Networking" section and look for the documentation about said subject. It would be a no-frills, more or less laconic documentation in cooking receipt style. Maybe with a nice sober style sheet, but not too fancy. More important, the article you stumble upon would be approved for the version of Slackware you are running, so if you duly follow the receipt, it's going to JustWork(tm).

Last edited by kikinovak; 08-17-2012 at 08:43 AM.
 
1 members found this post helpful.
Old 08-17-2012, 08:38 AM   #18
vharishankar
Senior Member
 
Registered: Dec 2003
Posts: 3,142
Blog Entries: 4

Rep: Reputation: 121Reputation: 121
deleted.

Last edited by vharishankar; 11-02-2012 at 12:43 PM.
 
Old 08-17-2012, 08:45 AM   #19
kikinovak
Senior Member
 
Registered: Jun 2011
Location: Montpezat (South France)
Distribution: Slackware, Slackware64
Posts: 1,489

Original Poster
Rep: Reputation: 662Reputation: 662Reputation: 662Reputation: 662Reputation: 662Reputation: 662
My favourite Linus Torvalds quote, as an inspiration. I got it printed out and pinned it over my work desk, right next to the UNIX - LIVE FREE OR DIE plate:

Quote:
Originally Posted by Linus Torvalds
Nobody should start to undertake a large project. You start with a small _trivial_ project, and you should never expect it to get large. If you do, you'll just overdesign and generally think it is more important than it likely is at that stage. Or worse, you might be scared away by the sheer size of the work you envision. So start small, and think about the details. Don't think about some big picture and fancy design. If it doesn't solve some fairly immediate need, it's almost certainly over-designed. And don't expect people to jump in and help you. That's not how these things work. You need to get something half-way _useful_ first, and then others will say "hey, that _almost_ works for me", and they'll get involved in the project.
 
5 members found this post helpful.
Old 08-17-2012, 08:54 AM   #20
whizje
Member
 
Registered: Sep 2008
Location: The Netherlands
Distribution: Slackware64 current
Posts: 582

Rep: Reputation: 129Reputation: 129
I also would like to assist. My English skills aren't super. But a got a lot of experience with the hardware side of pc's and servers.
 
Old 08-17-2012, 08:58 AM   #21
whizje
Member
 
Registered: Sep 2008
Location: The Netherlands
Distribution: Slackware64 current
Posts: 582

Rep: Reputation: 129Reputation: 129
What would be preferred, built on one of the existing sources slackwiki or the slackware wiki at LQ or start from scratch.
 
Old 08-17-2012, 09:07 AM   #22
dugan
Senior Member
 
Registered: Nov 2003
Location: Canada
Distribution: distro hopper
Posts: 4,546

Rep: Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386
I think a good use for a wiki would not be a collection of random howtos (that's already what SlackWiki is), but an actual book along the lines of The Slackbook or SlackBasics. I would even suggest actually starting from the SlackBasics book; it's GPL-licensed, so the legalities shouldn't be a problem.
 
Old 08-17-2012, 09:10 AM   #23
kikinovak
Senior Member
 
Registered: Jun 2011
Location: Montpezat (South France)
Distribution: Slackware, Slackware64
Posts: 1,489

Original Poster
Rep: Reputation: 662Reputation: 662Reputation: 662Reputation: 662Reputation: 662Reputation: 662
Quote:
Originally Posted by whizje View Post
What would be preferred, built on one of the existing sources slackwiki or the slackware wiki at LQ or start from scratch.
In my humble opinion, the first thing to do here would be to host a mailing list somewhere, something like slackdocs@example.org, and then everyboy who's interested join this list.

Next step would be to discuss fundamental questions like the one above. I think AlienBob is specifically right about one point: first, you need the Vision. Like "how is it going to be when it's finished?" So the first thing to do is discussing the Vision thing: how, where, how many, ... I know the usual approach is "OK, I'm gonna put this piece of information online and share it with others, and then we'll see, maybe others will join in, and who knows, after a while it's going to be a complete documentation". I know this manner of working (for practicing it also), but I think another approach is needed here. I like to take the SlackBuilds.org folks as an example, because they got their act together and made "nails with heads". Before SlackBuilds.org, there were just a few homebrew sites scattered over the web, some of them very good actually (AlienBob, slacky.it, slackware-fr, etc.) but now everything is really in one place, in a very appealing and sober presentation.
 
Old 08-17-2012, 09:12 AM   #24
kikinovak
Senior Member
 
Registered: Jun 2011
Location: Montpezat (South France)
Distribution: Slackware, Slackware64
Posts: 1,489

Original Poster
Rep: Reputation: 662Reputation: 662Reputation: 662Reputation: 662Reputation: 662Reputation: 662
Quote:
Originally Posted by dugan View Post
I think a good use for a wiki would not be a collection of random howtos (that's already what SlackWiki is), but an actual book along the lines of The Slackbook or SlackBasics. I would even suggest actually starting from the SlackBasics book; it's GPL-licensed, so the legalities shouldn't be a problem.
I think you can even have the best of both worlds. Start the site out with a "skeleton", an abstract. Then folks will fill in the sections gradually, in no particular order, until pretty much everything is fleshed out.
 
Old 08-17-2012, 09:21 AM   #25
sycamorex
LQ Veteran
 
Registered: Nov 2005
Location: London
Distribution: Slackware64-current
Posts: 5,524
Blog Entries: 1

Rep: Reputation: 997Reputation: 997Reputation: 997Reputation: 997Reputation: 997Reputation: 997Reputation: 997Reputation: 997
Quote:
Originally Posted by kikinovak View Post
I think you can even have the best of both worlds. Start the site out with a "skeleton", an abstract. Then folks will fill in the sections gradually, in no particular order, until pretty much everything is fleshed out.
Yeah, a well thought over skeleton/structure would go first and then over time people would populate particular sections.
 
Old 08-17-2012, 09:33 AM   #26
Totoro-kun
Member
 
Registered: Nov 2010
Location: Kaunas, Lithuania
Distribution: Slackware
Posts: 162

Rep: Reputation: 45
This is a great Idea, I was trying to think out something similar for a while (Even bought a domain slacknotes.org). But your ideas go way further than that. So if possible, an attempt to create slackdocs.org should be made.

I really like the ideas of keeping version specific documentation and Eric's idea about contributors responsibility to update their documentation when/if necessary.

I would certainly contribute few documents in that fashion.

EDIT
Just some thoughts about wiki stuff. While wiki engines really seem like a comfortable means to write, store and maintain information, they can also be very discouraging for a slacking users to start using them. Since you have to learn a syntax and that alone for a slacking user like me it's often a deciding factor not to write document. Plus different syntax for different wiki engines does not really help.

Also I do not like to search them (Arch Wiki being one shining exception), because of the reasons already mentioned here, like hitting an empty first page without useful navigation. It's not a problem when you know what you search for, but there are quite some times when you don't. There for as a user, I would certainly prefer clean documentation site with simple navigation over wiki stuff where you can't find anything without having to use search.

A solution might be to contribute documents in odf (since there would be administrating team, which could adapt them to a site format). There might be even better ideas I'm sure. But the fact is, if you want contributions, you have to make it simple for people to do, because in this material era, we value things which are scarce and time is one of them. Wild nature should be the other one with very high value, but I some times wonder if it actually is, but thats another topic, sorry. Anyway, is there any ideas on how to make contributions as simple and as little time consuming as possible?

Last edited by Totoro-kun; 08-17-2012 at 11:04 AM.
 
Old 08-17-2012, 10:50 AM   #27
rinias
Member
 
Registered: May 2009
Distribution: Slackware64-14.0
Posts: 58

Rep: Reputation: 18
Quote:
Originally Posted by dugan View Post
I think a good use for a wiki would not be a collection of random howtos (that's already what SlackWiki is), but an actual book along the lines of The Slackbook or SlackBasics. I would even suggest actually starting from the SlackBasics book; it's GPL-licensed, so the legalities shouldn't be a problem.
Maybe it's just silly, but this was the sort of thing I was contemplating. Would it not be possible to copy the information from the beta Slackbook into a wiki and then open it up to the community to keep up to date? Perhaps, as mentioned before, updates should be moderated, but how better to bring the Slackbook current than to make it into a wiki?

I do think that Kiki's idea about having a documentation browser is a good idea, but it could even be a separate project from the actual documentation, which could be supplied in some sort of standard formatting easily manipulated for display in different styles. (OK, I don't actually know how possible that is, but the idea seems to have merit, non? So, there could be a wiki, an online browser and perhaps even a local SlackDocs program - or something - all referencing the same data. Or, maybe I'm just nuts.)

In any case, as much as I - and certainly others - appreciate the effort Alan Hicks has put into the Slackbook, I don't think we should rely on that as our 'official' documentation. If, in the future, someone wants to put out a Slackware book - like Kiki has done with his tome, then it's a great opportunity for them! But we should have some evolving source of accurate documentation that we can easily access, if any at all. So, let's do it, or drop it!

As I said in the other threads about the Slackbook which surfaced recently, I will lend my support in whatever way I can.
 
Old 08-17-2012, 11:17 AM   #28
dugan
Senior Member
 
Registered: Nov 2003
Location: Canada
Distribution: distro hopper
Posts: 4,546

Rep: Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386
Here's an earlier thread in which a book-style wiki was brought up:

http://www.linuxquestions.org/questi...-2009-a-735819

The TOC for this project had better be more well thought out than this prior attempt:

http://en.wikibooks.org/wiki/Slackersbible

Last edited by dugan; 08-17-2012 at 11:18 AM.
 
Old 08-17-2012, 12:22 PM   #29
dugan
Senior Member
 
Registered: Nov 2003
Location: Canada
Distribution: distro hopper
Posts: 4,546

Rep: Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386Reputation: 1386
Quote:
Originally Posted by lolnameless View Post
sorry i laughed
and one thing, am i the only guy who consider all wiki as a secondary,untrusted source?
Honestly, yes, I think you are.

(And just of of curiosity, what was your first language? It's clearly not English. For one thing, it's "casualness", not "casualty"; a "casualty" is someone who was hurt or killed in a war).

Quote:
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.
I'd say more, but I'm not confident that I understand what you're saying.

Last edited by dugan; 08-17-2012 at 12:39 PM.
 
1 members found this post helpful.
Old 08-17-2012, 12:27 PM   #30
OldHolborn
Member
 
Registered: Jul 2012
Distribution: Slackware!
Posts: 31

Rep: Reputation: 10
+1 for an archlinux style wiki

-1 to a odf/pdf/doc style one

The Arch wiki is easily navigated in console browsers links and lynx. It looks great in lynx too! When viewed from within Firefox it is clean and consistent, elegant in its simplicity.

Absolutely perfect for Slackware.
 
  


Reply

Tags
documentation, slackware


Thread Tools Search this Thread
Search this Thread:

Advanced Search

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is Off
HTML code is Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Linux Documentation Project ask for Help jdd Linux - News 0 09-15-2008 01:37 AM
beginners documentation project? ichrispa LQ Suggestions & Feedback 1 01-13-2006 05:19 AM
The Windows Documentation Project CoolAJ86 General 3 08-29-2005 08:05 PM
The Fedora Documentation Project the shadows Fedora 0 03-21-2004 11:01 PM
Documentation project paradoxlight General 1 10-16-2003 10:24 PM


All times are GMT -5. The time now is 08:16 AM.

Main Menu
My LQ
Write for LQ
LinuxQuestions.org is looking for people interested in writing Editorials, Articles, Reviews, and more. If you'd like to contribute content, let us know.
Main Menu
Syndicate
RSS1  Latest Threads
RSS1  LQ News
Twitter: @linuxquestions
identi.ca: @linuxquestions
Facebook: linuxquestions Google+: linuxquestions
Open Source Consulting | Domain Registration