Changing/Improving HowTos & Documentation

[wobo]

Reading this thread something very basic comes to my mind: during previous years the target group for such HowTos has changed a bit. When we talked about "new users" or "poor immigrants" in former times we talked about users who had some basic knowledge from their Windows, some even knew what a prompt is. Additionally there were printed manuals in the distribution boxes and lots of people were used to buy and actually read books like "Linux in a nutshell" or others.

Todays immigrants have nothing like that and are not used to read anything before using the software (they may start reading in special cases later). Learning by doing is the new buzz word. On top of that modern Windows is changing its character away from a computer operating system to a smartphone desktop. Consequently we have more and more users who do not know anything about such things like "what is a device" (related to Linux). Is it time to rethink documentation to adjust to these changes?

Take this very simple chapter about dumping an iso on a USB device. For good reasons there is a repeated warning about the danger of destroying data or even the whole system on the harddisk. Ok, now the user is already above 190 heartbeats/s. Then you tell him to use "dmesg" to find out the correct device. Huh? How is he supposed to use dmesg, or rather "what is this 'dmesg'"? After he took these two hurdles (including the one where he has to understand who 'root' is and how he becomes this 'root') he will be confronted with a list of messages where he has no clue about one single line of it.

Having simple GUIs for that is one part of the answer (where we need a more detailed description of how to use it). The other part is to make explanations of using the beauty of the CLI more newbie-friendly.

While I have a picture in my brain how to improve the chapter I used as example, I'm also thinking about a general improvement in the wiki:

1. Create a section for basic explanations and HowTos, where short pages give the reader a basic knowledge, example "How and why to become root".
2. Whenever such a basic knowledge is needed in a normal HowTo or doc, link to that basic page.
2.a. At the top of a HowTo/Doc give a list of "Required knowledge for this HowTo" and give the links to the related pages. (like in Ubuntu wiki).

[viking60]

What is a wiki?
I agree though. It should be followed up with a completely new and curious forum here where it is absolutely forbidden to use complicated words.
with typical questions like:

Can I use MS-Office in Mageia?
The answer is Yes!
And that is it!

99% of all Linux users will feel the urge to elaborate heavily on this point but they should be thrown out/moderated of there long before Silverlight and Mono and Microsoft is even mentioned - there are other places for that.

Why is my apfelstrudel.exe file not installing when dobbel-clicked?
Linux has a different way of doing it - see below

What is a repository?
It is a database where the Linux Wizard has structured all the software in the world for you, and where you can download the programs you want to use.

Why is Linux better than Windows?
Well this is a good description

What is CLI?
And so on.....

Overall message should be that Linux is easy and usable - well because it is!
Linux geezers always start discussions that will scare away any greenhorn - that must be forbidden, because in the end it sends the message that Linux is complicated "Communistic Cancer" best kept away from.

Complicated questions, made to impress the audience, should be moderated out of that forum. Nothing should be above "Forest Gump" level.
I have not been to positive about Ubuntu in my time, but I think they have grasped that part well.

The data from the forum could serve as a FAQ for the wiki later.

With this combination (forum/Wiki) it should be possible to make newcomers feel very welcome. And it will probably be a good learning curve for experienced users to see what the new-comers really like to ask about, if they are encouraged to do so.

That is how you gain market shares instead of swapping them IMHO.

[wobo]

Well, my idea was not to write a new pamphlet why Windows users are the Big Losers.

And I don't see the need for a change in forum behavior - what all those people like the doktor and others do is just right IMHO. Question is followed by solution. If finding the solution needs more information, the helpers ask for that. If it turns out that the guy with the question can't follow, he gets more newbie-friendly advice and even step-by-step instructions.

The forum is a totally different place than the wiki, it is not the place to teach basic knowledge. That's what the wiki is there for and that is what I wanted to improve with my idea.

[doktor5000]

Yeah, sounds like a good idea, and seems really required these days.

So, volunteers, step forward please!


EDIT: Just saw the subsequent replies now, we definitely need some basic guidelines for the forum, too,
because also for the forums there are some very basic requirements, you don't imagine how often there are posts
like "Help, my machine (or part "foobar") doesn't work, how to fix?". Which doesn't even include any information
to directly help those people, and it's really exhausting to always identify the problem, ask for the basic needed informations
to do this, until then you can't even try to help such posters properly.

That's also on my TODO list, hope i can get that empty until Mageia 2 is released.

[alf]

Also in my opinion that seems to be awfully needful.

[doktor5000]

FWIW: https://wiki.mageia.org/en/Missing_documentation
Feel free to help reduce that list or propose new items.

[viking60]

Well, my idea was not to write a new pamphlet why Windows users are the Big Losers.

Not mine either, nor anyone else's afaict, but thanks for sharing (however irrelevant).

The differentiation of levels on the receiving end is my point, and to give them a special attention and place makes sense. As it is done here; it is only a question of adding another level before Basic support (could be called Greenhorns corner, coming from Windows etc.)

Mageia should be suitable for newcomers to Linux. For them a relevant comparison to Windows is necessary to get them started.
Or you could send them over to Ubuntu of course:

They are pretty good at this.....