LinuxQuestions.org
Visit the LQ Articles and Editorials section
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
 
LinkBack Search this Thread
Old 08-17-2012, 12:46 PM   #31
kikinovak
Senior Member
 
Registered: Jun 2011
Location: Montpezat (South France)
Distribution: Slackware, Slackware64
Posts: 1,408

Original Poster
Rep: Reputation: 629Reputation: 629Reputation: 629Reputation: 629Reputation: 629Reputation: 629

Quote:
Originally Posted by OldHolborn View Post
+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.
Yeah, seems like the best idea. It can happen from time to time that I'm working on an init-3-only server, and I need to do a quick search on the Internet. I use Lynx pretty much, actually (and BTW, SBo is quite Lynx-friendly also). I even test all my own websites on Lynx.

Anyone knows what backend the Arch people are using? I guess in matters of "Vision" (see above), having a Slackware-version of the Arch Linux wiki on slackdocs.org doesn't sound like a bad idea, even though it's not very original.
 
Old 08-17-2012, 12:50 PM   #32
dugan
Senior Member
 
Registered: Nov 2003
Location: Canada
Distribution: distro hopper
Posts: 4,235

Rep: Reputation: 1294Reputation: 1294Reputation: 1294Reputation: 1294Reputation: 1294Reputation: 1294Reputation: 1294Reputation: 1294Reputation: 1294
Quote:
Originally Posted by kikinovak View Post
Anyone knows what backend the Arch people are using?
MediaWiki.

Last edited by dugan; 08-17-2012 at 12:51 PM.
 
Old 08-17-2012, 01:46 PM   #33
whizje
Member
 
Registered: Sep 2008
Location: The Netherlands
Distribution: Slackware64 current
Posts: 582

Rep: Reputation: 129Reputation: 129
I emailed one of the administrators of archlinux.
Quote:
Hi Emilio,
As far as I'm concerned, I will be pleased to help you with some advices, however I can't speak on behalf of the other ArchWiki admins, you may have to contact them by yourself.
Anyway, by quickly reading the discussion you've linked, it seems you haven't decided yet whether to base your project on MediaWiki or some other software: since you'll understand that I really cannot follow the evolution of your project closely (not even the discussion on linuxquestions.org), I'd like to answer more specific questions than just be requested some "do's and dont's", or at least be presented a more definite idea, otherwise I really don't know where I could start from.
You may open a thread in archlinux.org's forum where you can post _only_ open questions to ArchWiki admins and other ArchWiki-experienced users (not just moving your whole discussion there): this way you'll make it easier for us to follow the discussion and you'll be more likely to obtain useful answers
In any case, one big problem that you'd better solve in advance, is making a decision about the possibility of making your project multilanguage or English-only: in the former case, note that MediaWiki doesn't have native support for multiple languages, and you'll have to find other solutions, e.g. the language suffixes we're using on the ArchWiki.

Well, let me know your thoughts
Dario "Kynikos" Giovannetti
So I think a wiki like archlinux is a good idea.
 
Old 08-17-2012, 02:25 PM   #34
Bazzaah
Member
 
Registered: Mar 2007
Distribution: Slackware64-current, Slackware64 14
Posts: 323

Rep: Reputation: 49
+1 for an Arch-style Slackware wiki.

I'd be more than happy to help with some of the writing if it looks likely to take off.

SlackBook covers a lot of ground too so should be used where possible.
 
Old 08-17-2012, 02:56 PM   #35
Woodsman
Senior Member
 
Registered: Oct 2005
Distribution: Slackware 14.0
Posts: 3,251

Rep: Reputation: 481Reputation: 481Reputation: 481Reputation: 481Reputation: 481
kikinovak,

A centralized location would be welcomed by many.

I like your proposed web site name, slackdocs,org. I like the idea of using using the same categories as slackbuilds.org.

I have worked in the technical writing field for three decades. Unlike slackbuilds.org that is administered by a handful of people to ensure build script quality, editing and proofreading are daunting tasks, even for experienced people. Especially when considering the volume of information such a web site will contain.

Unlike a slackbuild script, writing is not as limited in scope and nowhere as easily reviewed. Such a project invites an international audience and contributors with a wide range of English skills. There is a fine line with how much can be edited to maintain some semblance of style consistency while not discouraging participation. A written style guide will help, but heavy editorial participation is required to maintain the standards offered in a style guide.

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.

If using editorial reviews, then be forthright in any contribution policy that all submissions will be reviewed and that contributors who are not proficient in English can expect their contributions to be edited to one degree or another. Yet be sure when imposing such a policy that the original contributor agrees to the changes to ensure technical correctness and intent. Understand that such a process requires a lot of give-and-take by both people. In other words, several days or weeks might be needed before an article is posted to the web site.

As a community project, I recommend not worrying much about technical correctness. Yes, technical correctness is important, but don't expect or demand volunteer editors to be responsible for that aspect. The peer review process will resolve most technical correctness problems. That is, community members will discover problems with technical correctness. Fix obvious errors as they are found but rely upon the community to help with technical correctness. In other words, community participation will ensure a high degree of technical correctness without burdening the editorial staff.

The web site software is not as critical if you intend to use a dedicated staff of people to review all articles before posting because those people act as gatekeepers before anything is posted. If the goal is to treat the web site as a wide-scale community project and allow anybody to post articles, then a wiki approach probably is best. If embracing that latter approach, then to ensure some degree of quality be sure to post an editorial policy that articles can be edited and revised as necessary by anybody with a wiki account.

Have fun. :-)
 
4 members found this post helpful.
Old 08-17-2012, 03:17 PM   #36
astrogeek
Senior Member
 
Registered: Oct 2008
Distribution: Slackware: 12.1, 13.0, 13.1, 13.37, 14.0, 64-14, -current
Posts: 1,506

Rep: Reputation: 499Reputation: 499Reputation: 499Reputation: 499Reputation: 499
Quote:
Originally Posted by Woodsman View Post
I have worked in the technical writing field for three decades. Unlike slackbuilds.org that is administered by a handful of people to ensure build script quality, editing and proofreading are daunting tasks, even for experienced people. Especially when considering the volume of information such a web site will contain.
I had been hoping that you would join this discussion, your comments (and help) would be a welcomed source of light!

Editorial policy and hard work will make all the difference between a quality information source and a free-for-all forum, at least as much as the format (probably more so).
 
Old 08-17-2012, 03:32 PM   #37
kikinovak
Senior Member
 
Registered: Jun 2011
Location: Montpezat (South France)
Distribution: Slackware, Slackware64
Posts: 1,408

Original Poster
Rep: Reputation: 629Reputation: 629Reputation: 629Reputation: 629Reputation: 629Reputation: 629
Right, here goes. First things first.

Code:
Nous vous remercions d'avoir choisi BookMyName pour l'Enregistrement de
votre Nom de Domaine.
Voici les references de votre ordre d'enregistrement à conserver et à
rappeler lors de vos correspondances.

Date: 2012-08-17 22:30:27

Session: 2235/1450691

Déposant: KOVACS NICOLAS

Nom de Domaine: slackdocs.org

Durée: 1 an(s)
 
2 members found this post helpful.
Old 08-17-2012, 03:44 PM   #38
Alien Bob
Slackware Contributor
 
Registered: Sep 2005
Location: Eindhoven, The Netherlands
Distribution: Slackware
Posts: 5,111

Rep: Reputation: Disabled
I fully agree with Woodsman that technical correctness is not where the focus of the site admins should be. The author of an article will know best, and will take care of the technical correctness of what he submits. The editors/admins have to make sure that the text is accessible and legible.

I do want to promote a Wiki for the project, because it will allow any aspiring author to work freely on his or her article(s) while profiting from a Wiki's revision control and easy editing. A wiki will draw in many more people than when setting up a (.odt) document based site. The Wiki would have to offer an export facility that lets you export an article to .odt or docbook format. Dokuwiki can do that, Mediawiki too probably.

More important I think, is that Dokuwiki is able to work with page approvals:

Any page will be in draft mode until an administrator hits the "Approved" button. Non-admin users will only see approved pages (and their own draft pages of course) which will allow people to work in close co-operation with an admin to polish an article to the point of being print-ready. As long as the page is under construction, it will not be visible for the general public.
The group-ACL is another thing to mention: you can define sections (or "namespaces") of the Wiki that are editable by a limited group of people. That way, a team of authors can work on a series of related articles without being bothered by other members of the Wiki.

Whatever the choice of Wiki software would be, there are a few stages that have to be passed first.
  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.
  7. more? definitely. I can not come up with something else though

Oh, with regard to the site's hostname. Patrick is fine with using docs.slackware.com for this if you do want an affiliation with the mother ship.

Eric

Last edited by Alien Bob; 08-17-2012 at 04:06 PM. Reason: Add the license question.
 
Old 08-17-2012, 03:52 PM   #39
dugan
Senior Member
 
Registered: Nov 2003
Location: Canada
Distribution: distro hopper
Posts: 4,235

Rep: Reputation: 1294Reputation: 1294Reputation: 1294Reputation: 1294Reputation: 1294Reputation: 1294Reputation: 1294Reputation: 1294Reputation: 1294
Kikinovak, if you want this to get off the ground then you're going to have to take charge in at least coming up with the structure and TOC.

I'll be happy to contribute content.
 
Old 08-17-2012, 04:09 PM   #40
kikinovak
Senior Member
 
Registered: Jun 2011
Location: Montpezat (South France)
Distribution: Slackware, Slackware64
Posts: 1,408

Original Poster
Rep: Reputation: 629Reputation: 629Reputation: 629Reputation: 629Reputation: 629Reputation: 629
I can only say so much: WOW!

Never thought my initial message this morning would trigger all these fine responses.

I must have bought the slackdocs.org name about the same minute AlienBob told me about docs.slackware.com, so I'll be happy to simply redirect. You can't do better than docs.slackware.com.

During the days to come I'll do much thinking - and taking notes - about structure and organization, and I'm sure many of you guys will do something similar. I suggest for a beginning to adhere to the KISS principle: communicate via this forum thread, until we find something more apt, be it some sort of meta-wiki or some mailing list.

A quick idea concerning languages, as an aside. I guess 100 % of Slackware users have at least a basic grasp of the English language, otherwise they'd probably use, erm, a more i18n-friendly distro So my first idea would be to simply stick to english. I fear some babylonian mess otherwise. It seems to me english is Slackware's "official language", in the sense that in the Vatican you'd better be proficient in Latin to get along.

Does docs.slackware.com include some hosting, or does that have to be found? Me, I have a dedicated server in France that's fully mine. It's currently running Debian Squeeze, but I plan to move it to Slackware 13.37 around the first week of September. I'm a bit busy during the ten days to come, big install and maintenance work here. Sometimes I may not be as responsive as I'd like to be.
 
Old 08-17-2012, 04:10 PM   #41
Alien Bob
Slackware Contributor
 
Registered: Sep 2005
Location: Eindhoven, The Netherlands
Distribution: Slackware
Posts: 5,111

Rep: Reputation: Disabled
Structure and TOC could be taken from the ArchWiki as a starting point. It can always be revised later on. I can setup a first version of a Wiki software on taper.alienbase.nl if you want, unless someone already took care of finding a good host.

What the documentation site should also offer, come to think of it, is a download link with the complete site documentation in a single tarball, so that copies can be setup easily, and more importantly, language adaptations can be created. English is not everyone's language. With Dokuwiki, you do not have a SQL database at all - the content is contained in text files in a self-contained directory structure, which is easy for zipping up as part of a maintenance cron job.

Eric
 
Old 08-17-2012, 04:13 PM   #42
Alien Bob
Slackware Contributor
 
Registered: Sep 2005
Location: Eindhoven, The Netherlands
Distribution: Slackware
Posts: 5,111

Rep: Reputation: Disabled
Quote:
Originally Posted by kikinovak View Post
Does docs.slackware.com include some hosting, or does that have to be found?
It would just be hostname mapping for a server's IP address. No hosting. However, I do have taper.alienbase,nl which is a sponsored virtual server that I have full control over.

Eric
 
Old 08-17-2012, 04:50 PM   #43
sycamorex
LQ Veteran
 
Registered: Nov 2005
Location: London
Distribution: Slackware64-current
Posts: 5,403
Blog Entries: 1

Rep: Reputation: 951Reputation: 951Reputation: 951Reputation: 951Reputation: 951Reputation: 951Reputation: 951Reputation: 951
I'm glad it looks like something is actually happening. I'll be more than happy to contribute.
 
Old 08-17-2012, 04:54 PM   #44
whizje
Member
 
Registered: Sep 2008
Location: The Netherlands
Distribution: Slackware64 current
Posts: 582

Rep: Reputation: 129Reputation: 129
It seems wise to start with English, but it is important to think what you want to do with other languages. Are we gonna host all languages or like archlinux host only English and make interlinks to sites who made a translation. Keeping everything on one site gives more control and cohesion. But also more responsibility.
 
Old 08-17-2012, 06:02 PM   #45
Alien Bob
Slackware Contributor
 
Registered: Sep 2005
Location: Eindhoven, The Netherlands
Distribution: Slackware
Posts: 5,111

Rep: Reputation: Disabled
To get a feeling for Dokuwiki, see http://taper.alienbase.nl/dokuwiki/ , try to create an account there and play with creating pages. Contact me at my alien at slackware.com email to get more privileges (basically that'll be limited to those who voiced their interest in getting involved with this documentation project). I consider this wiki as expendable, even though you should not really be able to thrash it, but if it starts off desirably, who knows what it will grow into.

Eric
 
  


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
Trackbacks are Off
Pingbacks are On
Refbacks are 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 05:58 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