# Making things clearer - writing for dummies

**URL:** <https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180>\
**Category:** Documentation\
**Created:** [5 May 2020 19:30 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180 "2020-05-05T19:30:40Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![ms](https://community.ipfire.org/user_avatar/community.ipfire.org/ms/32/16615_2.png) [@ms](https://community.ipfire.org/u/ms)\
**Post date:** [5 May 2020 19:30 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/1 "2020-05-05T19:30:41Z")

</div>

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](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](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

---

<div class="post-metadata">

**Author:** ![jon](https://community.ipfire.org/user_avatar/community.ipfire.org/jon/32/15363_2.png) [@jon](https://community.ipfire.org/u/jon)\
**Post date:** [5 May 2020 19:58 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/2 "2020-05-05T19:58:01Z")

</div>

> 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.

 ![Screen Shot 2020-05-05 at 1.24.55 PM](https://community.ipfire.org/uploads/default/original/2X/3/30e19d5e4c48d1d4e2ae7abb7b5ee0473d2147cb.png)

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”:

- Here, read this first and come back with questions:
- [wiki.ipfire.org - Search results for 'safe search'](https://wiki.ipfire.org/search?q=safe+search)
- [blog.ipfire.org - Search results for 'safe search'](https://blog.ipfire.org/search?q=safe+search)

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](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](https://wiki.ipfire.org/configuration/network/proxy/wui_conf/auth)  
[wiki.ipfire.org - Ident Authentication](https://wiki.ipfire.org/configuration/network/proxy/wui_conf/auth/identd)  
[wiki.ipfire.org - LDAP Authentication](https://wiki.ipfire.org/configuration/network/proxy/wui_conf/auth/ldap)  
[wiki.ipfire.org - RADIUS Authentication](https://wiki.ipfire.org/configuration/network/proxy/wui_conf/auth/radius)

**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'](https://wiki.ipfire.org/search?q=fixme)

---

<div class="post-metadata">

**Author:** ![teejay](https://community.ipfire.org/user_avatar/community.ipfire.org/teejay/32/5078_2.png) [@teejay](https://community.ipfire.org/u/teejay)\
**Post date:** [5 May 2020 20:08 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/3 "2020-05-05T20:08:31Z")

</div>

> [@ms](#):
>
> Do you have any concerns why people might be unsuccessful with the wiki?

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

---

<div class="post-metadata">

**Author:** ![jon](https://community.ipfire.org/user_avatar/community.ipfire.org/jon/32/15363_2.png) [@jon](https://community.ipfire.org/u/jon)\
**Post date:** [5 May 2020 20:18 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/4 "2020-05-05T20:18:33Z")

</div>

> As an example ([wiki.ipfire.org - Virtual Environments](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.

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!” 🙃

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

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

---

<div class="post-metadata">

**Author:** ![ms](https://community.ipfire.org/user_avatar/community.ipfire.org/ms/32/16615_2.png) [@ms](https://community.ipfire.org/u/ms)\
**Post date:** [5 May 2020 20:18 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/5 "2020-05-05T20:18:54Z")

</div>

> [@jon](#):
>
> 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.

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.

> [@jon](#):
>
> I partially disagree. I think you need to point people in the right direction. In other words, “read this and come back with questions”

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.

> [@jon](#):
>
> 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.

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.

> [@jon](#):
>
> In my honest opinion, this should priority number 2. The first priority should be the fill in the blanks.

What are those blanks in your opinion?

---

<div class="post-metadata">

**Author:** ![ms](https://community.ipfire.org/user_avatar/community.ipfire.org/ms/32/16615_2.png) [@ms](https://community.ipfire.org/u/ms)\
**Post date:** [5 May 2020 20:19 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/6 "2020-05-05T20:19:08Z")

</div>

> [@teejay](#):
>
> well, it’s easier to ask questions rather than to search and read.

Well that cannot really be the answer…

---

<div class="post-metadata">

**Author:** ![ms](https://community.ipfire.org/user_avatar/community.ipfire.org/ms/32/16615_2.png) [@ms](https://community.ipfire.org/u/ms)\
**Post date:** [5 May 2020 20:20 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/7 "2020-05-05T20:20:04Z")

</div>

> [@jon](#):
>
> 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!” 🙃

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.

---

<div class="post-metadata">

**Author:** ![jon](https://community.ipfire.org/user_avatar/community.ipfire.org/jon/32/15363_2.png) [@jon](https://community.ipfire.org/u/jon)\
**Post date:** [5 May 2020 20:31 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/8 "2020-05-05T20:31:18Z")

</div>

> [@ms](#):
>
> What are those blanks in your opinion?

These wiki pages:

> **[Ident Authentication](https://www.ipfire.org/docs/configuration/network/proxy/wui_conf/auth/identd)**

> **[LDAP Authentication](https://www.ipfire.org/docs/configuration/network/proxy/wui_conf/auth/ldap)**

> **[RADIUS Authentication](https://www.ipfire.org/docs/configuration/network/proxy/wui_conf/auth/radius)**

and these pages with the word “FIXME”

> **[IPFire Documentation - Search: 'fixme'](https://www.ipfire.org/docs/search?q=fixme)**
>
> Search Results for 'fixme'

---

<div class="post-metadata">

**Author:** ![ms](https://community.ipfire.org/user_avatar/community.ipfire.org/ms/32/16615_2.png) [@ms](https://community.ipfire.org/u/ms)\
**Post date:** [5 May 2020 20:33 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/9 "2020-05-05T20:33:19Z")

</div>

> [@jon](#):
>
> and these pages with the word “FIXME”  
> [www.ipfire.org - Search results for '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.

---

<div class="post-metadata">

**Author:** ![anon33261557](https://community.ipfire.org/letter_avatar_proxy/v4/letter/a/eb9ed0/32.png) [@anon33261557](https://community.ipfire.org/u/anon33261557)\
**Post date:** [5 May 2020 20:43 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/10 "2020-05-05T20:43:38Z")

</div>

> [@ms](#):
>
> > [@teejay](#):
> >
> > well, it’s easier to ask questions rather than to search and read.
> 
> Well that cannot really be the answer…

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.

---

<div class="post-metadata">

**Author:** ![ms](https://community.ipfire.org/user_avatar/community.ipfire.org/ms/32/16615_2.png) [@ms](https://community.ipfire.org/u/ms)\
**Post date:** [5 May 2020 20:53 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/11 "2020-05-05T20:53:50Z")

</div>

> [@anon33261557](#):
>
> 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?

---

<div class="post-metadata">

**Author:** ![anon33261557](https://community.ipfire.org/letter_avatar_proxy/v4/letter/a/eb9ed0/32.png) [@anon33261557](https://community.ipfire.org/u/anon33261557)\
**Post date:** [5 May 2020 21:04 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/12 "2020-05-05T21:04:46Z")

</div>

The Wiki is the point for people like me that love to read 😉 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.

---

<div class="post-metadata">

**Author:** ![bloater99](https://community.ipfire.org/user_avatar/community.ipfire.org/bloater99/32/15796_2.png) [@bloater99](https://community.ipfire.org/u/bloater99)\
**Post date:** [5 May 2020 21:15 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/13 "2020-05-05T21:15:27Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![ms](https://community.ipfire.org/user_avatar/community.ipfire.org/ms/32/16615_2.png) [@ms](https://community.ipfire.org/u/ms)\
**Post date:** [5 May 2020 21:39 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/14 "2020-05-05T21:39:58Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![rodneyp](https://community.ipfire.org/user_avatar/community.ipfire.org/rodneyp/32/16575_2.png) [@rodneyp](https://community.ipfire.org/u/rodneyp)\
**Post date:** [6 May 2020 04:24 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/15 "2020-05-06T04:24:01Z")

</div>

> [@ms](#):
>
> 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.

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.

> [@ms](#):
>
> 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…

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.

> [@ms](#):
>
> As an example ([Virtual Environments - IPFire](https://wiki.ipfire.org/hardware/virtual)): I have almost entirely removed the pages about virtualisation.

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.

> [@ms](#):
>
> 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.

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”

> [@ms](#):
>
> Do you have any concerns why people might be unsuccessful with the wiki?

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.

---

<div class="post-metadata">

**Author:** ![ms](https://community.ipfire.org/user_avatar/community.ipfire.org/ms/32/16615_2.png) [@ms](https://community.ipfire.org/u/ms)\
**Post date:** [6 May 2020 08:08 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/16 "2020-05-06T08:08:11Z")

</div>

> [@rodneyp](#):
>
> 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.

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.

> [@rodneyp](#):
>
> 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.

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.

> [@rodneyp](#):
>
> 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.

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.

> [@rodneyp](#):
>
> 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.

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.

> [@rodneyp](#):
>
> 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.

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.

---

<div class="post-metadata">

**Author:** ![anon65703081](https://community.ipfire.org/letter_avatar_proxy/v4/letter/a/90ced4/32.png) [@anon65703081](https://community.ipfire.org/u/anon65703081)\
**Post date:** [6 May 2020 11:23 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/17 "2020-05-06T11:23:26Z")

</div>

> [@ms](#):
>
> I would also like to make things clearer.

just my humble opinion:

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

> **[List of Public DNS Servers](https://www.ipfire.org/docs/dns/public-servers)**

> **[VLAN with IPFire](https://www.ipfire.org/docs/optimization/vlan?revision=2019-01-16T23%3A57%3A04)**

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

se also: [IPFire Community - The IPFire Community Forum](https://forum.ipfire.org/viewtopic.php?f=22&t=23205&sid=abfec843f2eb68da2310831fe059d48b&start=15#p126788)

I think a structure and design like here could help.

---

<div class="post-metadata">

**Author:** ![ms](https://community.ipfire.org/user_avatar/community.ipfire.org/ms/32/16615_2.png) [@ms](https://community.ipfire.org/u/ms)\
**Post date:** [6 May 2020 12:30 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/18 "2020-05-06T12:30:25Z")

</div>

> [@anon65703081](#):
>
> [wiki.ipfire.org - List of Public DNS Servers](https://wiki.ipfire.org/dns/public-servers)

Why is this illegible?

> [@anon65703081](#):
>
> [https://wiki.ipfire.org/optimization/vlan?revision=2019-01-16T23:57:04](https://wiki.ipfire.org/optimization/vlan?revision=2019-01-16T23:57:04)

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

> [@anon65703081](#):
>
> I think a structure and design like here could help.

What is wrong with the design?

---

<div class="post-metadata">

**Author:** ![anon65703081](https://community.ipfire.org/letter_avatar_proxy/v4/letter/a/90ced4/32.png) [@anon65703081](https://community.ipfire.org/u/anon65703081)\
**Post date:** [6 May 2020 13:21 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/19 "2020-05-06T13:21:34Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![ms](https://community.ipfire.org/user_avatar/community.ipfire.org/ms/32/16615_2.png) [@ms](https://community.ipfire.org/u/ms)\
**Post date:** [6 May 2020 13:34 UTC](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180/20 "2020-05-06T13:34:34Z")

</div>

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

 ![Screenshot 2020-05-06 at 14.33.07](https://community.ipfire.org/uploads/default/original/2X/e/ea414246c1cf8f68876811c2bd830a3750728734.png)

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

[Next page](https://community.ipfire.org/t/making-things-clearer-writing-for-dummies/2180.md?page=2)
