Confusing Documentation for Newbies

[Ben.]

Hi,
I'm running pfSense for years and am quite familiar with it. Now I want to check if I should switch to OPNsense, therefor I need to read the documentation a little.

My problem is that the Wiki feels very confusing. Am I the only one having problems with it?

What I feel makes it difficult to read:

- I can't see if there are subpages to a chapter. When I click on it I can see the small "tree structure" icon. I would prefer to see directly if there is more behind this point.
- The structure feels not straightforward. After initial installation I want to set up rules. I can't find a chapter "Firewalling". Either it's hidden in a sub-chapter but as I am new to OPNsense, I feel "lost".
- What role does "HowTos" play? Is it part of the documentation or are these specific scenarios which are described in more detail?

I know, you can use the search function, but if you are new and want to get a first overview and the principles behind, I feel very difficult.

So my question to you: Am I using it wrong? Is there a better place to start?

Thanks for your feedback and help

[Ricardo]

Hi,
I'm running pfSense for years and am quite familiar with it. Now I want to check if I should switch to OPNsense, therefor I need to read the documentation a little.

My problem is that the Wiki feels very confusing. Am I the only one having problems with it?

What I feel makes it difficult to read:

- I can't see if there are subpages to a chapter. When I click on it I can see the small "tree structure" icon. I would prefer to see directly if there is more behind this point.
- The structure feels not straightforward. After initial installation I want to set up rules. I can't find a chapter "Firewalling". Either it's hidden in a sub-chapter but as I am new to OPNsense, I feel "lost".
- What role does "HowTos" play? Is it part of the documentation or are these specific scenarios which are described in more detail?

I know, you can use the search function, but if you are new and want to get a first overview and the principles behind, I feel very difficult.

So my question to you: Am I using it wrong? Is there a better place to start?

Thanks for your feedback and help

I must agree with every single word you said. The reason people in this forum keep asking the same 20 questions  over and over and over, that docs are in very bad shape. The wiki is not at the level of being called as documentation. I'd spend money on a proper written book, only problem nobody will write a proper book about a software that changes every 2 weeks :-(

[fabian]

I must agree with every single word you said. The reason people in this forum keep asking the same 20 questions  over and over and over, that docs are in very bad shape. The wiki is not at the level of being called as documentation. I'd spend money on a proper written book, only problem nobody will write a proper book about a software that changes every 2 weeks :-(

That's not correct. Somebody has written a book called "Der OPNsense-Praktiker" (https://der-opnsense-praktiker.github.io/).
Most of the documentation is in the How To section because it is the section which shows how to set something up with screenshots. The others are usually more technical or project background (API documentation, development, project information etc.). The pages in the user manual which are no how to pages, are most likely to explain how things work together or why things in OPNsense are how they are as well as some intro for beginners.

[marjohn56]

I must agree with every single word you said. The reason people in this forum keep asking the same 20 questions  over and over and over, that docs are in very bad shape. The wiki is not at the level of being called as documentation. I'd spend money on a proper written book, only problem nobody will write a proper book about a software that changes every 2 weeks :-(

And of course, you could always help by submitting something to the wiki once you find out how it works, that's what some of us do, you then help others. Yes, things change quite often, that's because OPNsense is evolving - and long may it continue to do so.

[Ricardo]

I must agree with every single word you said. The reason people in this forum keep asking the same 20 questions  over and over and over, that docs are in very bad shape. The wiki is not at the level of being called as documentation. I'd spend money on a proper written book, only problem nobody will write a proper book about a software that changes every 2 weeks :-(

And of course, you could always help by submitting something to the wiki once you find out how it works, that's what some of us do, you then help others. Yes, things change quite often, that's because OPNsense is evolving - and long may it continue to do so.

I know its difficult for you guys -who revolve around this product 24/7/365 and know most of its parts by heart- to believe me, that the product documentation needs a general overhaul. Take this as positive constructive  criticism, no reason to be offended at it.

I always recommend in such situations, try to find some volunteer friends, who are not IT illiterates (know some Linux/BSD basics and familiar with the workings of a generic firewall), but (important!) have zero experience with this specific product. Sit with them together, and tell them:

"Hey buddy, here is a "new" firewall called Opnsense, here is a blank PC or SoC. Goal is to have a running router with some basic firewall setup and a working WAN connection. Pls try to install it without assistance. Try to use only the wiki.opnsense.org and try to find answer for all your questions there."

I would record all the obstacles, that the wiki was unable to solve, thus would generate +1 more unnecessary thread opened here in this forum.

https://wiki.opnsense.org/manual/install.html --> for example, this one seems to me a very rudimentary draft page: the CLI setup for the interfaces has been finished with these 2 lines, no further explanation, no helping hand if one got stuck here or what to do if someone makes a mistake:

After installation the system will prompt you for the interface assignment, if you ignore this then default settings are applied. Installation ends with the login prompt.


Some links to more "advanced" setup like WAN-PPPOE would be feasible.

"OPNsense installation images are provided on a regular bases together with mayor versions in January and July. More information on our release schedule is available from our package repository see README" -->
https://pkg.opnsense.org/releases/16.1/README : this URL is broken for example.

No description of the naming convention of the releases: <2digit YEAR code>.<1 digit code of the month when the major release was issued>.<bi-weekly updates until the next major releases comes>. Most probably this is all trivial for experienced people, but not really for newcomers.

https://wiki.opnsense.org/manual.html --> I dont really understand what this picture of a happy dutch guy has to do with the manual, but whatever. Ok, to be ontopic: separation of the so called user manual vs. developer manual would suggest as a normal firewall admin all I can possible need, will be found in the user manual. Unless I am a plugin developer, in which case I should consult the developer manual. But this is clearly not the case, in order to even understand the basic architecture of this product (which is hardly pictured anywhere), I need to read through the developer-centric manual. As I'm not developer, for me its rather difficult to understand, which parts of the modification makes me a "developer" while other changes are by nature of the product, and even normal firewall admins have to do it via that way.

Again, no blaming, just would highlight this as an unacknowledged issue.

[mimugmail]

Also no blaming from my side: you can always fork in GitHub, so your changes and add a PR. Then it would be from the community, to the community

[Ricardo]

I think thats what I am going to do. After I learned how Github basics works.

The only thing worries me, why nobody from the thousands of community member has already added these simple parts? Is your approval system, that makes people give up the effort to make docs better?

[mimugmail]

Nope, there's just no volunteer willing to add / rewrite. Fabian and I already added many stuff, but we are only two and spend more time on contributing code

[marjohn56]

"OPNsense installation images are provided on a regular bases together with mayor versions in January and July. More information on our release schedule is available from our package repository see README" -->
https://pkg.opnsense.org/releases/16.1/README : this URL is broken for example.

Fixed, on the next set of docs pull that is now corrected.

[opnsenseuser]

:-)

[opnsenseuser]

I think thats what I am going to do. After I learned how Github basics works.

The only thing worries me, why nobody from the thousands of community member has already added these simple parts? Is your approval system, that makes people give up the effort to make docs better?

Since I feel that you would enjoy it, I think that from now on you will be the chosen person who can make a documentary about the best free firewall.
By doing so, you would make the entire community very happy and relieve many developers.

[Ricardo]

I do understand jokes, its just that I dont like them

Ok, to be serious: (possibly) the core team are wasting a lot of their precious time if the frequently asked questions are answered every single time in this forum. Instead of getting the same answer (as it has already been typed into the database in the past), copy-paste it to a relevant place on the wiki. Instant win! No need to type it twice, forum is not inflated unnecessarily, and wiki pages are progressing at least into some form of completion.

[mimugmail]

From my side, I wasn't joking.

If you can give me an advise what exactly has to change and how I can think about it.

But really, we are all doing this in our spare time, and I mean the coding, not the writing of documentation.
Nobody earns money with this and just do this for fun (not profit ) .

So, if you would like to add some changes, go on. You can also just write it down in Word and I'll pull it in. But dont change too much as it might get refused.

[opnsenseuser]

I do understand jokes, its just that I dont like them

Ok, to be serious: (possibly) the core team are wasting a lot of their precious time if the frequently asked questions are answered every single time in this forum. Instead of getting the same answer (as it has already been typed into the database in the past), copy-paste it to a relevant place on the wiki. Instant win! No need to type it twice, forum is not inflated unnecessarily, and wiki pages are progressing at least into some form of completion.

That was not meant as a joke.
Unfortunately, there are a lot of members who offer good solutions, but then prefer to let others do it.

Counting, unfortunately, only does what is implemented.

[mimugmail]

I think thats what I am going to do. After I learned how Github basics works.

If you need help in this you can ping me via IRC. I'm always there during workhours (CEST)