LinuxQuestions.org
Welcome to the most active Linux Forum on the web.
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-20-2012, 02:26 PM   #151
PrinceCruise
Member
 
Registered: Aug 2009
Location: /Universe/Earth/India/Pune
Distribution: Slackware64 14.1/Current, CentOS 6.5/7.0
Posts: 722

Rep: Reputation: Disabled

Well, great initiative folks. Already registered.
Looking forward for a new chapter in Slackware legendary, and of course to contribute.

Regards.
 
Old 08-20-2012, 03:44 PM   #152
Alien Bob
Slackware Contributor
 
Registered: Sep 2005
Location: Eindhoven, The Netherlands
Distribution: Slackware
Posts: 5,195

Rep: Reputation: Disabled
OK guys,

This discussion is moving a lot faster than I can manage, having a daytime job and a family and all.
So, a lot of sentiments were voiced, a lot of opinions were formed, everyone is eager to make a Slackware Documentation Project a success.

Good!

So far, there have been quite a few people with contributions to the new Wiki, which is the spirit I was hoping for. This thread gives hints and insights as to where you think this project should go. Even though not everybody has the same ideas about how to shape the initiative, I enjoyed the posts that I read which I picked out of the 11 pages that are already here :-)

Let me try to organize my thoughts a bit, so that you know where I want to go with this project.

First: the wiki based approach. It is great for community editing, and if done smart it will flourish. Think of ArchWiki but also Wikipedia. I understand that it clashes with the traditional approach of writing a book, but we all can see what is happening to the SlackBook.org site. The new documentation project should be organic, dynamic. But, it will need structure as well. The admins will have to come up with a set of starting pages defining the high-level topic areas. Think of Slackware, the distro (philosophy, history, future, ...). A Beginner's Guide (essentially, what's now the SlackBook). Advanced Slackware administration topics. Software and hardware HOWTOs. User pages. This list will grow.
Note that this structure should take its strength from the Wiki capabilities. It is not a TOC which you are used to see in a book. A Wiki does not read like a book! Some of Woodsman's ideas about a TOC will be useable, but not all. That TOC looks like it is designed for an actual book.
Take the ArchWiki again as an example. That Wiki is hugely popular, not only with Arch Linux users. Why? Because it covers anything you could imagine about that distro. It is not limited by the contraints which you would have in a book-based approach. Yes, there is structure, yes, there is a TOC. But that TOC is dynamic, it is created by the Wiki out of the Category tags of the individual pages. Our DokuWiki has the {{tag>some_string}} markup element which I want to use much in the way that the Mediawiki's [[Category:some_string]] markup works. So: we are not going to hard-code our TOC! Let the Wiki organize itself.

Second: vision. I know what I want with the project, but that idea does not have to be everyone's. I wrote on the start page "Welcome to the SlackDocs Wiki: your primary source for Slackware Linux documentation on the web". I think that that is important: to start your search for Slackware knowledge in the wiki, but the Wiki does not have to be the end point. I think it is pointless to absorb all the available information you can find on the web in there. Let's build new knowledge in our Wiki and at the same time create a page (or pages) with the purpose of listing the location of every piece of information about Slackware that can be found on the Internet.
Another idea I have about the Wiki is how to maintain a high level of quality. That brings me to the next point.

Third: control. Like SlackBuilds.org, I think that the project will benefit from a certain measure of control. Looking at what's already there in the Wiki, I see content but no real structure. The foundation I laid out (in a hurry) by largely copying the ArchWiki start page is only partly effective, and the structure is only coming from discussions between me and the authors about where the new articles should belong - discussions in the #slackdocs Freenode channel for instance. A free-for-all is not going to give this project a permanent place in history. I propose to have a few admins who maintain infrastructure, a larger team of site editors who do the proofreading and approvals and guidance; and of course the larger group of people who write the actual articles.
Woodsman's criteria of what a good article looks like can be used as part of a style guide for the editors perhaps.

Fourth: running the project somewhat like Slackware or not? Should it be a real community effort or should "Slackware" i.e. its developers have a say in this by acting as Benevolent Dictators? I ask this because of the fact that I would like to see docs.slackware.com becoming a pointer to this Wiki and mentioned on the Slackware site. But doing so creates a dependency: people will expect Slackware to be at least partially responsible for the site's content. Alternatively, kikinovak registered slackdocs.org which is much looser connected to the distro. Using that hostname, and opting to be fully independent from Slackware, will make it a different site. This is a choice which is still open. I will actively pull (or lead) the project if it has a Slackware affiliation, but I will relinquish control of the project if it is to become a pure community based project (but will contribute articles then).

Fifth: openness. I hinted at Wikipedia and ArchWiki in the beginning. Those are MediaWiki based. The mediawiki does not know about access control. The mediawiki software was written to empower every man or woman to become an author. But, I don't know if you have ever looked at the Talk pages for Wikipedia articles? Behind every major article there is a continuous "fight" about what that article should look like. Edits are reverted and the reverts are again reverted. That is the reason why I opted for the DokuWiki software which has been designed as a collaborative tool for groups of people to write documentation, including control over who does what.
I do not want our Wiki to be completely "open", allowing everyone to change texts at will. The mechanism of having site editors will not have any effect if an author can publish whatever he feels like. That is why I want to enable the "publish" plugin next weekend, after which any edit to a page will put that page in "Draft mode". Wiki visitors will not see the draft version, just the old approved page. A site editor can verify the changes and click the "Approved" button if he agrees to the edit. Anyone with a Wiki account will be able to see all the drafts by the way!

Sixth: licenses. So far, I have seen parts of the Slack Book being copied into the Wiki without any form of attribution. I am not OK with this. Someone in this thread wrote that he was going to copy my network documentation article into the new Wiki. I am not OK with this either.
If any existing information is going to be copied into the Wiki, I want the original source as well as original author(s) mentioned in the footer of the article. Always look at the license terms under which the original is presented! For instance, the original edition of the Slack Book was GPL licensed, which forced Alan Hicks to do a full re-write of the book in his own wordings - the current Beta Book.
I do not want the Wiki to become a copy-cat. Be creative folks! There is a writer inside of you! We need unique content, and realize that it takes time to grow. Copying existing documentation will give the Wiki some "body" but it must not become a goal in itself.
And we will have editors who will guide you towards a good end product.


More to follow. I will also write this somewhere in the Wiki.

Eric
 
2 members found this post helpful.
Old 08-20-2012, 03:45 PM   #153
diwljina
Member
 
Registered: Jun 2009
Distribution: Slackware, Debian
Posts: 105

Rep: Reputation: 8
Am I mistaken or the original idea behind this is lost? One of the reason slackbuilds.org is that successful is because every peace of the software there has it's own maintainer. So, following that principle, one would notify administrators with a new article idea (so there would be no doubled effort if someone else is working on a same thing), link would be created on appropriate place with something like "reserved" in brackets and author would write that article and would be responsible for it's maintaining. Everyone else is welcome to propose a change, but updating article would be author's responsibility (and of course, admins would be in charge of approving that article).

If someone does not wont to maintain it anymore, he would drop it just like on slackbuilds.org and someone else would take it.
 
1 members found this post helpful.
Old 08-20-2012, 04:11 PM   #154
Alien Bob
Slackware Contributor
 
Registered: Sep 2005
Location: Eindhoven, The Netherlands
Distribution: Slackware
Posts: 5,195

Rep: Reputation: Disabled
Quote:
Originally Posted by diwljina View Post
Am I mistaken or the original idea behind this is lost? One of the reason slackbuilds.org is that successful is because every peace of the software there has it's own maintainer. So, following that principle, one would notify administrators with a new article idea (so there would be no doubled effort if someone else is working on a same thing), link would be created on appropriate place with something like "reserved" in brackets and author would write that article and would be responsible for it's maintaining. Everyone else is welcome to propose a change, but updating article would be author's responsibility (and of course, admins would be in charge of approving that article).

If someone does not wont to maintain it anymore, he would drop it just like on slackbuilds.org and someone else would take it.
A valid remark indeed.
Yes, I would like to see that article authors feel an ownership for the content they write. I also think it is reasonable to discuss with the site admins your ideas for new articles, so that you don't duplicate someone else's efforts. A page placeholder is easy to accomplish of course. You will be able to write your article in your own time, at your own pace, because as long as it does not get approved by an editor, it will be in draft mode and will not be visible to Wiki visitors (although it will be visible to your fellow authors... you can accept or discard any helpful hints of course. The editor will be your friend).

Just like I mentioned earlier when I talked about copying someone else's work and adding that to the Wiki: every article should list its primary authors and contributors in the footer. I would like to create some templates for that purpose, so that when you create a new page, some of the useful markup will already be there for you.

Eric
 
1 members found this post helpful.
Old 08-20-2012, 10:11 PM   #155
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:38 PM.
 
Old 08-20-2012, 10:26 PM   #156
kikinovak
Senior Member
 
Registered: Jun 2011
Location: Montpezat (South France)
Distribution: ElementaryOS, Ubuntu LTS, Slackware
Posts: 1,512

Original Poster
Rep: Reputation: 699Reputation: 699Reputation: 699Reputation: 699Reputation: 699Reputation: 699
I wanted first to go for the TOC-type, but after reading the previous detailed statements, I guess I'm convinced that the loose wiki structure may be the way to go.

Woodsman's detailed TOC - or maybe the Slackbook's TOC, enhanced with additional entries - can figure in a page entitled something like "Stuff that can be covered here", an initial brainstorming list.
 
Old 08-21-2012, 01:24 AM   #157
aster30
LQ Newbie
 
Registered: Aug 2012
Distribution: slackware
Posts: 3

Rep: Reputation: Disabled
Quote:
Fourth: running the project somewhat like Slackware or not?
IMHO this project needs a leadership team. A full community automanaged projects cannot live a long time. What about working on slackdocs.org for beginning, organise ourself, ..., and migrate under docs.slackware.com when the basic doc is nearly ready. Depending of what we will do : following a "toc" (or clearly TODO list) with clear objectives, or growing in empirical way, without basic list of articles.
 
Old 08-21-2012, 01:55 AM   #158
kikinovak
Senior Member
 
Registered: Jun 2011
Location: Montpezat (South France)
Distribution: ElementaryOS, Ubuntu LTS, Slackware
Posts: 1,512

Original Poster
Rep: Reputation: 699Reputation: 699Reputation: 699Reputation: 699Reputation: 699Reputation: 699
Quote:
Originally Posted by Alien Bob View Post
Sixth: licenses. So far, I have seen parts of the Slack Book being copied into the Wiki without any form of attribution. I am not OK with this. Someone in this thread wrote that he was going to copy my network documentation article into the new Wiki. I am not OK with this either.
If any existing information is going to be copied into the Wiki, I want the original source as well as original author(s) mentioned in the footer of the article. Always look at the license terms under which the original is presented! For instance, the original edition of the Slack Book was GPL licensed, which forced Alan Hicks to do a full re-write of the book in his own wordings - the current Beta Book.
I do not want the Wiki to become a copy-cat. Be creative folks! There is a writer inside of you! We need unique content, and realize that it takes time to grow. Copying existing documentation will give the Wiki some "body" but it must not become a goal in itself.
And we will have editors who will guide you towards a good end product.
Eric
I second the suggestion to mention the author's name in an article. Why not adopt a principle similar to the one that can be found on SlackBuilds.org? Every SlackBuild script mentions not only the author, but also all the guys who modified it.

On the other hand, there are some articles (well, in fact, all of them) on your personal wiki (think Samba, networking, ...) that would do great here. What prevents you from moving them over here, signed of course? Thumbs up for your remark on creativity, but I don't want to improve something that's already good. The better is the enemy of the good, as we say here in France.
 
Old 08-21-2012, 03:02 AM   #159
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:38 PM.
 
Old 08-21-2012, 03:13 AM   #160
Alien Bob
Slackware Contributor
 
Registered: Sep 2005
Location: Eindhoven, The Netherlands
Distribution: Slackware
Posts: 5,195

Rep: Reputation: Disabled
Quote:
Originally Posted by kikinovak View Post
I wanted first to go for the TOC-type, but after reading the previous detailed statements, I guess I'm convinced that the loose wiki structure may be the way to go.

Woodsman's detailed TOC - or maybe the Slackbook's TOC, enhanced with additional entries - can figure in a page entitled something like "Stuff that can be covered here", an initial brainstorming list.
My first idea after seeing Woodsman's list was that this would be a good and structured write-up for "what subjects do we want to have covered in this Wiki". An aspiring author could then pick any of these topics, strike through the entry on the proposition page, and start writing. A site editor will then decide what is the best namespace for the article and check that the page contains the right tags so that it will automatically show up in the Wiki TOC.

Eric
 
Old 08-21-2012, 03:17 AM   #161
Alien Bob
Slackware Contributor
 
Registered: Sep 2005
Location: Eindhoven, The Netherlands
Distribution: Slackware
Posts: 5,195

Rep: Reputation: Disabled
Quote:
Originally Posted by vharishankar View Post
Thanks for clarifying those ideas, Eric.

I vote against a book-like structure with numbered chapters, sections and subsections. Even if there are no numbers, imposing a book-like ToC will be more suitable for a non-Wiki, DocBook-like documentation project.

I feel each Wiki page is meant to be self-contained for its own topic, along with links to refer to other related topics. Let there be no restrictions at present for topics of coverage and allow contributors to write about whatever topic they feel they are good in.
The wiki will not be setup with (numbered) chapters but will be topic driven. There should not be limits to the topics covered in the Wiki, as long as there is relevance to Slackware Linux and its community.

I do think that we should write a FAQ entry stating reasons for rejecting an idea or an article: we do not want to cover the same topic twice, we do not want to see "distro bashing" or otherwise obnoxious texts, and so on. Bad writing or spelling skills should not be a reason for rejection... that is where an editor would step in.

Eric
 
Old 08-21-2012, 03:24 AM   #162
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:38 PM.
 
Old 08-21-2012, 03:30 AM   #163
sycamorex
LQ Veteran
 
Registered: Nov 2005
Location: London
Distribution: Slackware64-current
Posts: 5,546
Blog Entries: 1

Rep: Reputation: 1001Reputation: 1001Reputation: 1001Reputation: 1001Reputation: 1001Reputation: 1001Reputation: 1001Reputation: 1001
Quote:
Originally Posted by Alien Bob View Post
The wiki will not be setup with (numbered) chapters but will be topic driven. There should not be limits to the topics covered in the Wiki, as long as there is relevance to Slackware Linux and its community.
Can you provide examples of some top-level categories/topics? Having them would enable people focus on particular areas.

I can't imagine it would just be a long list of unordered articles/topics.
 
Old 08-21-2012, 05:17 AM   #164
brianL
LQ 5k Club
 
Registered: Jan 2006
Location: Oldham, Lancs, England
Distribution: Slackware & Slackware64 14.1
Posts: 6,930
Blog Entries: 51

Rep: Reputation: Disabled
Quote:
Originally Posted by Alien Bob View Post
My first idea after seeing Woodsman's list was that this would be a good and structured write-up for "what subjects do we want to have covered in this Wiki". An aspiring author could then pick any of these topics, strike through the entry on the proposition page, and start writing. A site editor will then decide what is the best namespace for the article and check that the page contains the right tags so that it will automatically show up in the Wiki TOC.

Eric
Yes, that sounds like a good idea to me. More like a ToDo list, than a TOC.
 
Old 08-21-2012, 06:32 AM   #165
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:38 PM.
 
  


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 07:06 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