SlackwareThis Forum is for the discussion of Slackware Linux.
Notices
Welcome to LinuxQuestions.org, a friendly and active Linux Community.
You are currently viewing LQ as a guest. By joining our community you will have the ability to post topics, receive our newsletter, use the advanced search, subscribe to threads and access many other special features. Registration is quick, simple and absolutely free. Join our community today!
Note that registered members see fewer ads, and ContentLink is completely disabled once you log in.
If you have any problems with the registration process or your account login, please contact us. If you need to reset your password, click here.
Having a problem logging in? Please visit this page to clear all LQ-related cookies.
Get a virtual cloud desktop with the Linux distro that you want in less than five minutes with Shells! With over 10 pre-installed distros to choose from, the worry-free installation life is here! Whether you are a digital nomad or just looking for flexibility, Shells can put your Linux machine on the device that you want to use.
Exclusive for LQ members, get up to 45% off per month. Click here for more info.
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.
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
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.
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).
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)
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.
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
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.
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.
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.
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.
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.
LinuxQuestions.org is looking for people interested in writing
Editorials, Articles, Reviews, and more. If you'd like to contribute
content, let us know.
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. 
