Making things clearer - writing for dummies

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

8 Likes

We fell that people do not read the wiki.

agree!

That could have multiple reasons: Either they do not know the wiki exists…

For noobies I believe “not knowing” is the main reason. I’d like to see a Wiki link on the top of the Community page.

Maybe similar to this Node-RED (Discourse) Community that adds a IPFire Wiki link. I’m not looking for something this busy - just the Wiki, the Downloads, maybe the GitHub. Simple and clean. This will not solve the problem but it is one step in the right direction.

That could have multiple reasons: … or they simply did not care to read anything and let other people do their work for them.

I suggest to push them in that direction and make a suggestion to the “uninitiated”:

In other words - Let Me Search That For You.
PS - I love this site! It has such power!

https://lmgtfy.com/?q=site%3Aipfire.org+safe+search&s=t

PS - my safe search examples above isn’t meant to slight anyone. It was just a simple example!

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.

Agree - You can lead them to water but cannot make them drink. All that can be done is to make sure the Documentation is in order.

I do NOT want to pick up people from where they are any more.

I partially disagree. I think you need to point people in the right direction. In other words, “read this and come back with questions”

Please keep in mind responses could scare people away (or lack of responses). If you could review the old IPCop forum there was lots of nasty in responses. It took me months to get up the courage for a first post. Or a second post… I never felt welcome there.

But what I would like to do is making things shorter. Short pages are good.

In my honest opinion, this should priority number 2. The first priority should be the fill in the blanks.

Wiki pages like:
Authentication methods - wiki.ipfire.org - Authentication Methods
wiki.ipfire.org - Ident Authentication
wiki.ipfire.org - LDAP Authentication
wiki.ipfire.org - RADIUS Authentication

Note: I’ve added a quick template to these pages (scroll down on these pages), but I am not technical enough to add any real or worthy information.

More blanks - any Wiki page with the word “FIXME” —> wiki.ipfire.org - Search results for 'fixme'

well, it’s easier to ask questions rather than to search and read.

1 Like

As an example (wiki.ipfire.org - Virtual Environments): I have almost entirely removed the pages about virtualisation. There is no reason why we should give people arguments about why to do this.

Partially agree - I think a virtual machine is very useful for a testing environment. That is all I use it for. Anything else, like a IPFire production environment riding on a VM, should not be supported.

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.

For new policy - I’d like to see a new addon include Wiki documentation before it is released to all. The Y2019 IPS documentation was a great example of the Role Model Behavior. I better not hear anyone yell “bulls#i+ bingo!” :upside_down_face:

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

My biggest concern is filling in the blanks (as mentioned above)

Yeah, this is kind of what. I do not want to talk about. The wiki is there. People who found this have scrolled past it. It does not need a button.

Yes, for everything we want to cover, of course. But we should explicitly NOT educate people and give them Computer Networks 101. If there is a severe lack of knowledge, they should not run IPFire. It is dangerous.

I get similar PMs from people on here. Complaints about “nobody responded to my post” or that the response has not been helpful and they found that therefore rude. I could not see any rudeness in any of those.

What are those blanks in your opinion?

Well that cannot really be the answer…

1 Like

I am encouraging that every time, but we struggle to get the releases out there and documentation is for most developers unfortunately a second priority.

These wiki pages:

and these pages with the word “FIXME”
https://wiki.ipfire.org/search?q=fixme

I just opened this and I am deleting loads of. pages. They are unfinished, outdated (Windows Vista and Windows 7 are gone) and simply describe things that are not even part of IPFire.

That is what I mean… There is so much stuff that the actual information I am looking for can be really hard to find sometimes.

I dont understand this as answer its a explanation why people doing it. And because they do it that way you can not reach this people.

My personal opinion is, whatever you try with the wiki it doesnt help to reach that people. They ask anyway.

And what would be the point then to have the wiki at all?

The Wiki is the point for people like me that love to read :wink: And normally i read alot before i ask a single question.

In other words put your time in the wiki for the people who want read it, put dont spent anymore time to reach all people. You can not win this race.

I think it would be cool if each page of the Web UI could have a Help link that takes you to the appropriate wiki page. That would get more people aware of and using the wiki.

2 Likes

This suggestion has been made plenty of times. I would be happy to accept patches, but so far nobody wanted to work on it.

All of the above and probably more are true, in my experience with other discussion lists. People have become used to purchasing a device/accessory that “just works” and can be disinclined to investigate problems.

I also agree with others that we are unlikely to stop that behaviour, but as Jon points out, as far as possible, our best counter to this mind-set ought to be to refer to the relevant page of the wiki and provide additional suggestions only if that page does not adequately answer the question.

I agree with keeping the wiki as short as possible, addressing only IPFire specific issues and linking to external sites, such as Wikipedia, for more detailed explanation.

Dropping reference to Virtualisation makes sense. It’s useful for testing instances, but has multiple drawbacks for operational environments - assumes a very secure hypervisor instance, configuring multiple networks for VM is complicated and puts a number of “failure points” in one box.

I generally support what you have done and propose. As a relatively minor contributor to the wiki, I am prepared to add/amend small segments, but not to delete whole sections.

Many of the time-consuming posts are from beginners who apparently either expected an IPFire installation to “just work” or have insufficient understanding of IP networking to do a basic configuration.

Part of the solution could be to make an IPFire installation “just work”, as a strong, but uncomplicated firewall. I regularly install openSUSE and ocassionally Ubuntu-based distributions that achieve this on x86 hardware. IPFire might not be far from this objective, but the detail would be a separate thread under “Installation”

There is a case that the wiki is too late in the process for beginners, particularly if they are not inclined to read documentation. They are able to download an image without first acknowledging that they have read the hardware requirements as well as recognising that an elementary understanding of IP networking is (currently) required. A fairly straight-forward modification of the Download page might change that. A similar step could also be added to the opening boot screen of the Installer, or made part of the licence acceptance screen, to cater for those who got the image from a mirror/acquaintance.

True. The problem though is that you do not “purchase” IPFire. There is no free support coming with it. There is a place where you can ask questions, but that does not guarantee responses within minutes.

That is the way to go. But I am also trying to find a way, that we do not even have the post in the first place.

I am drafting some guidelines right now. That is something for another topic. However, I would not recommend to link to most basic things. SSH should be known. What an IP address must be known. If people lack that knowledge, they should not be running IPFire.

This was only an example, but I guess it is a good one: If you do not know how to set up networking on your hypervisor, then you should not run anything on it. People need to educate themselves.

We used to have a splash page after a successful download once, which I potentially want to bring back. I don’t think it worked very well tho.

just my humble opinion:

the wiki should be more clearly formulated at many places. These pages for example are quite illegible

this might scare off some people. i found the old wiki was more eye friendly.

se also: IPFire Community

I think a structure and design like here could help.

Why is this illegible?

Absolutely agree. There are too many pages that explain some console work which is absolutely unnecessary.

What is wrong with the design?

for example: https://www.meine-erste-homepage.com/fussballtabelle.php is better to read like https://wiki.ipfire.org/dns/public-servers

It’s hanging out the right hand side of my screen…

But why is it better? Bigger font size? Font? Contrast to background?