If you clicked on a discussion link to a page which does not exist yet, you see the following message:

It's really as easy as following that advice, click on the "create this page" tab (or button or whatever you call it) above the page. Then write something, sign with your name and click "Save".

Or did you have a different problem?

Eric

I went to the discussion tab of the first article Slackware.

http://docs.slackware.com/talk:slackware:slackware

I couldn't see how to add an entry so, as a guess, I selected to edit the page. I saved by edit but nothing changes. Does it have to be approved? Should I not be "editing" the discussion entry as it was done by another?

Sorry to bog down this discussion in mechanics. Perhaps I should follow up in a chat room. What channel is used to discuss this topic?

It's #slackdocs on Freenode

Edit: I guess you've already found it out.

Yes I found the slackdocs chat room and Alien Bob solved my problem.

For those other "new guys" like me. It is proper to select the discussion page and edit the page by leaving the previous content alone and adding your content at the bottom. You should separate your content by drawing a line (six dashes).

Also add your name or nickname and a time/date stamp.

Eric,

Is there an IRC channel for this project?

@vtel57 See two posts above.

Oh, thanks. Yes, I already subscribe to that IRC channel.

In this post, I will call "Slackware Documentation System" or SDS the whole documentation system, including all that is needed to make it work.

In a systems engineering perspective, the SDS will include:
- the content,
- the metadata,
- the hardware and software used,
- the processes: gathering information, writing, reviewing, releasing, updating, organizing, administrating, managing security...
- the organization (who does what when and how),
- the decision subsystem,
- the people involved in the processes as the administrators, contributors, reviewers and even the end users.

The SDS is not limited to a wiki: one can consider that this forum, the documentation already included in Slackware including READMEs, HOWTOs, help texts in the installer and comments in Slackware scripts are part of it as well.

In systems engineering parlance, the SDS can be viewed as an "enabling system" for Slackware Linux itself as it allows or facilitate its usage.

Let me list the goals of the SDS, as I see it. Take what follows as examples, I am not a decider.

I won't distinguish between intermediate and ultimate goals, and though numbered to facilitate the discussion they are listed below in no particular order.
(1) Encourage adoption of Slackware Linux by people using another Linux distribution or operating system in facilitating the migration.
(2) Soften the learning curve for people eager to use Slackware Linux.
(3) Help people looking for accurate information about Slackware Linux to find it.
(4) Allow people to use Slackware Linux effectively an efficiently.

To reach these goals, SDS features should fulfill its users needs, or if you prefer satisfy their requirements, as we can imagine them.

In turn these requirements depend on users' characteristics, situations and contexts and on what they would like to get, do or achieve with SDS' help -- let's call that the use cases.

As it's hard to believe that one documentation system can fully satisfy all requirements of all possible users, choices will have to be made. Let's call that scoping.

We should first ask ourselves "which use cases could be addressed by the SDS?", in other words "what could be SDS' scope" -- if not tomorrow, hopefully in a not so distant future.

Then, determine the scope and clarify the goals of the SDS will be among the most important duties of the leaders -- let's call so those who will carry the vision and push to make it become reality.

I propose following use cases to prime the pump. Of course this is a non exhaustive list, again in no particular order:
(1) People with nearly no technical background, wanting to transition from Windows to Linux for home usage (may be because it's free, or to get rid of viruses, or in search of stability or reliability) with minimum hassle and risks, possibly with the help of persons of their acquaintance.
(2) People already using another Linux distribution, eager to try Slackware and needing to find their way in it and/or wishing to to know what is specific to it.
(3) People wanting to learn Linux through Slackware Linux' usage.
(4) People with intermediate level of knowledge (i.e. not intimidated by the command line, knowing some basic commands), eager to learn more about
Slackware Linux' configuration or administration and/or to optimize its usage.
(5) People wanting to set up, configure and administrate servers based on Slackware Linux.
(6) Sys admins in search of ways to better accomplish their tasks.
(7) People wanting to use a specific software or hardware, needing to know if they can do that with Slackware Linux.
(8) People wanting to install, configure Slackware Linux and ease maintenance tasks, for one of their friends or relatives.
(9) People wanting to install Slackware as a host system, to run a virtual machine in it, or to follow the LFS book, whatever.
(10) People wanting to create new content, updating or enhancing existing content (contributors or reviewers)
(11) People wanting to set up, configure, organize or administrate the SDS (admins)
(12) Et un raton laveur (untranslatable French joke).

The SDS should provide features allowing it to fulfill the needs and satisfy the requirements corresponding to those of these use cases which will be included in the scope.

Some of the needed features seem obvious and in fact are available in most wiki softwares, as for instance:
- allow to view(!) and edit remotely the content of pages through a web browser,
- associate metadata to pages, like dates of creation and last modification, author, keywords, categories, group of pages, language used,
- allow to search for, list and sort pages using the metadata,
- log all modifications (traceability) and allow to reverse it,
- allow to comment or discuss the content of a page,
- allow to grant or revoke rights to view, edit, comment to individuals or groups,
- allow users to register and connect, which give them access to specific features and rights,
- allow to organize and/or display the content in a structured way through indexes, TOCs, grouping, keywords, categories, ...
- allow to find pages including some text in the content, title or metadata ,
- allow to configure and administrate the system,
- allow to configure the appearance (through themes, for instance) and allow integration in a broader system
- allows to inform the users of modifications concerning the pages they are interested in
- offer localized versions of the UI
I won't list them all, people not familiar with wiki's usage can refer to Wikipedia or to Wiki Comparison
Specific features will be needed to address needs and requirements included in the scope.

I am not speaking only about features of the Wiki software, but about features of the SDS as a whole.

I am specially interested in the content's structure problem, as I believe that the success of failure of the SDS will largely depend on its adequacy to needs of users, the ability to easily find the information they look for being one of the most important ones.

So, TOC or not TOC?

I think that answer this question is premature. It is a "how" like question (the implementation, or the technical or organic choices), but functional choices (the "what" and the "why") should be made first. As we say here, "Ne mettons pas la charrue avant les boeufs".

The problem of information finding is complicated by the fact that there is big diversity in needs, because of the variety of use cases to address as well as of diversity in individual characteristics of users.

Some people will just look for a specific and precise information about a specific device, or application.

Others will like to acquire broader knowledge or know-how, as for instance "compile a kernel" "configure the network" or "install and configure Slackware".

It's difficult to cope with individual differences in ways of learning, time that people accept to dedicate to reading a documentation or technical background.

But at least we should try to address such a variety of needs in providing several ways to access information.

That is what some books authors try to do when they suggest "impatient people, go straight there" or "if you know that already you can skip these chapters" or "if you need a certification or degree you will need to read from A through Z"

Similarly we could provide some "typical paths" for some use cases, indexes for others, random searches for everybody, etc.

For instance for use case (1) we could list the topics which would form sort of a "survival guide for the Slackware Linux beginner", as "what is a terminal, the seven most useful commands, the main directories in Slackware, things that should be done or avoided ..."

For use case (2) we could address the startup process and its configuration (BSD like with SystemV ability), the package management, the configuration tasks through editing text files, the run levels, what is a slackbuild, where to find packages and slackbuilds, content and usage of /var/log/{packages, scripts}, recommended way to update and upgrade, recommended readings...

So for each of the use cases included in the scope we should ask ourself questions like: what is the relevant information, what is the level of details needed, in which order (if applicable) the content should be presented, what would be the relevant ways to give access to the content in this case ? For instance through a "search" feature, or categories listing, or a TOC specific to this use case proposing a list of pages not otherwise linked together, a sequence or group of pages, ...

Probably in some cases a very terse "how-to" simply listing the steps to follow will be relevant, in another cases more in depth explanations will be needed.

IMHO, only after the results of this analysis will have been synthesized the design and technical choices can be made in a relevant way.

That's a lot of work indeed, which should be organized by the leaders with participation of volunteers.

But this will give us better chances that time and effort devoted to writing documentation will fully benefit in reaching the accepted goals.

Sorry to have been maybe too theoretical or pedantic, thanks for having taken the time to read this boring long post, please excuse the syntactic and orthographic mistakes as English is not my native language.

3 members found this post helpful.

Don't apologize for your English, Didier. You communicate more proficiently in that language than many Americans I know.

deleted.

I think your post is a perfect example why it is a good idea that it'll be led by a member of Slackware core team If anything, this thread proved how diversified we are. Each person has their own ideas regarding the project. We are like a herd of cats, each going in a different direction.

Like we always say that we trust Pat's decisions regarding the shape of Slackware, I trust Eric's decisions regarding the shape of the wiki.

Edit: Besides, it's not about who owns/controls it. Let's just have some proper documentation in one place.

1 members found this post helpful.

You know, I'm running a company too (http://www.microlinux.fr), and installing and managing Linux networks is my day to day job. So in theory, you should consider the fact that any helpful message that you post on this forum is more or less support for my company, since I do benefit from it.

You have probably a scary idea of the word "corporate". Yes, I am the manager of a company, and I can hand you a nice professional-looking business card. But, you know, I'm also the secretary and the accountant as well as the cleaning woman here. I'm right now drinking my coffee with my window open to the South French countryside, listening to Pink Floyds Dark Side Of The Moon, walking barefoot and wearing old worn-out Levis Jeans and an old MOTÖRHEAD t-shirt. How's that for "corporate"?

Nah, relax.

A think a wiki is per defintion a community effort. And as a wiki is not a discussion board, I can imagination that there comes a statement on the wiki that the wiki is supported by slackware but that does not mean that the slackware team agrees with all content. With this I mean how you can add stuff to slackware, which the slackware team never would. Or a article which is critical over how slackware is run. I also understand that there are things the team absolutely does not want but I think that when it's a pure community effort you don't want them also.

deleted.

Because a wiki is a community effort it's easier to keep it updated. As a book is a team effort which is much harder to keep updated.
from wikipedia
I guess some people see it as a knowledge management database and others view it a notetaking apparatus.