From mboxrd@z Thu Jan 1 00:00:00 1970 From: Michael Tremer To: documentation@lists.ipfire.org Subject: Making things clearer - writing for dummies Date: Tue, 05 May 2020 15:55:41 +0100 Message-ID: <523E9D7B-78D1-42D2-8D42-43D46D02C8CF@ipfire.org> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="===============1869950167536960541==" List-Id: --===============1869950167536960541== Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Good morning, I spent some time today to edit the wiki. We had a rather longish discussion at our monthly telephone conference call a= bout 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. Pe= ople could not find what they are looking for - or they simply did not care t= o 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 fir= ewall. The latter is a really big concern, because we have people managing bu= siness 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 canno= t 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. Oth= erwise 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 soft= ware. But what I would like to do is making things shorter. Short pages are good. T= hey 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 evaluat= e 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 w= ill never make anyone happy. As an example (https://wiki.ipfire.org/hardware/virtual): I have almost entir= ely 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 a= nd that is what a new short page does. It has information about on what hyper= visors IPFire runs, but clearly states that that is a bad idea for multiple r= easons. People who really want to do this hopefully know why and what the potential p= roblems are. I would like to hear some feedback from the regular editors of the wiki if th= ese things make sense. Maybe we should write some kind of policy at some poin= t so summarise all these things for future editors. Do you have any concerns why people might be unsuccessful with the wiki? Best, -Michael --===============1869950167536960541==--