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.