Making things clearer - writing for dummies

[Michael Tremer <michael.tremer@ipfire.org>]

[-- Attachment #1: Type: text/plain, Size: 2881 bytes --]

Good morning,

I spent some time today to edit the wiki.

We had a rather longish discussion at our monthly telephone conference call about the state of the Community Portal and that we are all rather frustrated about what is going on there.

We fell that people do not read the wiki.

That could have multiple reasons: Either they do not know the wiki exists. People could not find what they are looking for - or they simply did not care to read anything and let other people do their work for them.

Not reading the wiki results in plenty of questions that have been answered a hundred times or simply should not be asked by a person who is running a firewall. The latter is a really big concern, because we have people managing business networks who are unable to SSH into their firewall. That is a security disaster waiting to blow up.

Since we have all limited time to reply to people - and patience in my case - I would like to propose to make some changes:

I do NOT want to pick up people from where they are any more. If people cannot install PuTTY then there is plenty of places that explain very well on how to double-click an EXE file. We have to ask for a minimum level of skill. Otherwise the wiki becomes very verbose and reading a guide about something that takes five clicks spends the first two pages on how to install required software.

But what I would like to do is making things shorter. Short pages are good. They are easy to read - even when someone is only reading headlines. They are easy to link to and people will find what is interesting instead of searching through too much text and image.

For example: The start page is shorter (https://wiki.ipfire.org). Links were hidden in text and they are now a simple bullet point list.

I would also like to make things clearer.

Very often, I have written things where in the end, the reader has to evaluate what is right for them. That clearly does not work. People are making poor decisions and do not understand why. Those are horrible support cases which will never make anyone happy.

As an example (https://wiki.ipfire.org/hardware/virtual): I have almost entirely removed the pages about virtualisation. There is no reason why we should give people arguments about why to do this. We should advocate the opposite and that is what a new short page does. It has information about on what hypervisors IPFire runs, but clearly states that that is a bad idea for multiple reasons.

People who really want to do this hopefully know why and what the potential problems are.

I would like to hear some feedback from the regular editors of the wiki if these things make sense. Maybe we should write some kind of policy at some point so summarise all these things for future editors.

Do you have any concerns why people might be unsuccessful with the wiki?

Best,
-Michael