Wiki: docs/user-guide/openvpn.server

@JW0914 You and I recently corresponded about a different wiki page that you felt people weren't reading. This led me to summarize my thoughts in a blog posting How to Write Wiki Pages So People Will Read Them

The VPN Server wiki page suffers from those problems. It doesn't meet two of the three criteria in the blog posting. ("Is this page for me?" - I can't tell. "Can I figure out what to do?" not really... I will concede the third point - you are deeply knowledgeable about the topic. But the information you provide, and its layout don't help me solve my problems.)

In the case of the OpenVPN Server page, the first thing I see (because it's highlighted in orange) is "Don't use Easy-RSA", with a bunch of jargon about using OpenSSL via an openssl.conf. (Whatever that means...)

I believe this is turning off your readers. When I encounter this kind of writing, it's easy to think, "I don't know enough to understand this page", and instead, post questions to the forum.

In any collaborative group like OpenWrt, there's room for mentoring of newcomers. New people coming into the project are its lifeblood. And the project's documentation is a primary mechanism for mentoring.

I believe every wiki page should have one or several introductory paragraphs that explain what the page is about. Further, it should tell people what to do, instead of warning about all the bad things you shouldn't do.

Please consider adding introductory text. Even if you don't take my suggestion, solicit feedback from the readers here about what might make the OpenVPN Server page more useful. Thank you for listening.

You have a far different ideology regarding wikis that I do not share (as I expressed multiple times in our previous conversation), and the wiki works as written.

  • Wikis are professional documents, or at least they should be, and as such, should be informative and concise.

    • I also believe wikis should be in a standardized format site wide, however, as I stated in our previous conversation, it's unfortunate most don't bother taking the hour or so to read through the DokuWiki plugins, especially the extremely versatile Wrap Plugin

      • Taking the time to layout a wiki with DocuWiki plugins breaks up the monotony of black text after black text. The latter of which is even more important nowadays when people have to create a TL;DR section since reading is [unfortunately] too time intensive for so many nowadays.

  • I will not write wikis in a format that serves the 10% you're clearly apart of and will write wikis in a manner that serves 90% of the people, 90% of the time.

  • How do I know the wiki works as written?

    • Because users who follow the instructions, as written, do not have issues, and repeatedly, when users believe the instructions are the issue, I've repeatedly performed the same exact steps laid out in the wiki and every single time, the wiki works.

      • Every time someone has an issue with this specific wiki (here, on the OpenWrt forum, as well as every other place I link to the wiki), with the exception of a single time when the wiki was ported from OpenWrt, it's always due to user error... every... single... time. And every single time, it's due to a user either not reading, or deviating from the instruction set.

    • If you believe otherwise, I encourage you to follow the wiki, as written, or better yet, if it will stop this, I'll follow the wiki exactly as written, and I'll post the terminal and log output of all steps performed.

If one doesn't want to take the time to read and understand a wiki, especially about something as important as a VPN, which, if configured incorrectly compromises the security of the VPN (thereby defeating the entire purpose of setting up a VPN), perhaps contemplating whether one should be setting up whatever it is they're setting up should be done currently, or when the user has time to dedicate to doing it correctly should be considered.

  • Since you clearly have the internet, why not use a search engine to search for whatever "jargon" you don't understand?

    • Since I'm a bit exasperated at this point at your repeated "jargon" comments, both here and in our prior conversation, I'll break down what you seem to believe is "jargon", which in actuality is relevant information, written in a fairly simplistic sentence:

      • "Easy-RSA does not create secure enough, nor proper, certs & has too many limitations, therefore OpenSSL should be utilized directly via an openssl.cnf"
        • "Easy-RSA does not create secure enough, nor proper, certs & has too many limitations"
          • This is self-explanatory...
            • Easy-RSA does not create secure enough, nor proper, certs: means it does not create secure enough certs with the proper KUs and EKUs
            • ...[Easy-RSA] has too many limitations: means the OpenVPN server, due to an Easy-RSA certificate, will have too many limitations, restricting how a VPN server can be configured.

        • "...therefore, OpenSSL should be utilized directly via an openssl.cnf"
          • This is also self-explanatory...
            • ...OpenSSL should be utilized directly: means openssl commands should be utilized
            • ...via an openssl.cnf: means the OpenSSL config file should be used

.

There is an introduction... @stangri added one, I edited it to remove the wordiness, then incorporated it into a tabbox with the Purpose being the first tab, Requirements being the second, and then to be helpful, an Editing tab showing how to use vim.

I'd encourage you to read the wiki, as last I checked, users should be warned what not to do if it's important, while being instructed what to do... I'd encourage you to view the headings in the ToC, as your statement lacks rationale and logic.

  • Reading does occur from the top downwards after all...

You have a far different ideology regarding wikis which at least 3 admins do not share.

1 Like

Thankfully, we don't have to agree. If you want wikis the way you three want them, then why don't you three write all the wikis and keep them updated and current?

  • If you don't like the way I write wikis, either ban me from writing wikis, as I will continue to format them as I've done, or deal with it..

  • What I do know is this... you three represent less than 0.01% of the OpenWrt/LEDE user base, and considering the vast majority do not have issues with the way I format OpenWrt/LEDE wikis, I'd say you're in the minority.

According to this the vast majority of users who voted on the issue (63%) are with the admins.

@stangri 3 users? Seriously lol That's what you consider "vast majority" as?

@tmomas Change my wiki and I will change it back. If you don't want people using DokuWiki formatting, then change your wiki software.

  • If I recall correctly, it was precisely this type of attitude that caused LEDE to fork off to begin with.

Here's a bit of perspective:

  • 3 admins and 3 users do not like the formatting of my wiki, and that wiki has existed for 2 1/2 years (it was created in July 2015)... so yes, I'd say you're in the 10%.
    • To put it bluntly, the world doesn't revolve around the 10%, as everything is created for an audience of 90% of people, 90% of the time. I'll let the history of my wiki speak for itself, as 6 people complaining about the formatting over two and a half years is pretty good in my book.

The LEDE admins should make the determination on how and in what format wiki articles are written.

Articles should have an approval process, just like writing for any website.

If you want to do your own thing, post them on your own site.

LEDE's site...LEDE's rules.

2 Likes

You must greatly overestimate your importance and importance of your article if you think it would cause massive uproar when poorly written. The facts is that out of the users who voted, just 3 users voted for your article over the old one. So in 2 and a half years, just 3 users liked your article.

I don't over-estimate the importance of it at all, and was simply stating a fact.

  • Common sense would dictate if users had issues with the formatting, it would have been brought up in a thread on the OpenWrt forum, the OpenVPN forum, the FreeNAS forum, as well as several others where I've linked to it over the years... the fact is it's only a select minority of 6 users on this forum which have complained about the formatting, and 4 of which couldn't quantify what issue they had with it.

    • What's fascinating is the one user who did quantify why they didn't like it criticized the information provided, over the previous wiki, of which provides no information other than a bunch of commands.

      • So is the issue the formatting, or the simple fact it appears many simply want a point and click setup where they don't have to read and understand what they're doing (which is quite dangerous when an incorrectly configured VPN can compromise it's security)?

  • The OpenWrt wiki has used DokuWiki for years, it's simply 99% of wiki writers refuse to take the time to read through the DokuWiki site prior to writing a wiki (this seems to be a recurring theme in general)? I digress to my previous point: "If you [@tmomas] don’t want people using DokuWiki formatting, then change your wiki software."

I create and/or format wikis to meet the needs of 90% of readers 90% of the time, and thus far, those disliking the layout and use of DokuWiki plugins falls into the 10% minority.

  • I'm not going to alter the way in which I format wikis to be direct, to the point, with concise language, no wordiness, and laid out in a coherent manner through the use of DokuWiki plugins... it's a disservice to whomever comes across the wiki to do it in any other way.

    • I am always open to suggestions, and have no issue with anyone adding to a wiki I write, as that's what's supposed to happen... different people are supposed to contribute over the life of a wiki. Sometimes I have to edit the wording of additions to make them less wordy or add in formatting to bring the additions in line with the current layout to prevent discombobulation, but I'll never remove content another adds (unless it's vastly non-relevant, factually inaccurate, or it's a question that's been posted to the wiki).

      • As I've stated, I don't share the same perspective as the 3 admins, nor should I, or any other user for that matter, have to or need to. The beauty of opensource is the collaboration between people who have different philosophies and perspectives.

Well, it lasted a little over 2 weeks, and you are back to throwing your condescending attitude around the LEDE site...but now, you are including admins in your nonsense.

Your inflated ego overrides your judgement, and your arrogance prevents you from providing anything of value here.

You are becoming irrelevant...that guy.

Since you seem to appreciate perspective, here is some for you...

At some point, those "three admins" (the 10% minority I think you called them) may decide you are no longer worth the trouble, and simply ban you from the LEDE site permanently.

If that happens, you have no one to blame but yourself.

1 Like

Ahem. I think this is evidence that users find hard to read your instructions.

I mean, some normal people try reading and doing, they fail because they somehow stray from your instructions (how?).

You (the instruction writer) try following your own instructions but you succeed.

This is just proof that people other than yourself have issues reading that stuff. Or I'm reading your statement wrong.

If you believe otherwise, I encourage you to follow the wiki, as written,

I'm used to read far worse documentation already, I should be able to pull that off if I try hard enough.

But I can tell you that I'm still finding that guide a bit confusing. Too much tabs, it must be more linear, top-down. It's already a complex topic as-is.

Every time someone has an issue with this specific wiki (here, on the OpenWrt forum, as well as every other place I link to the wiki), with the exception of a single time when the wiki was ported from OpenWrt, it’s always due to user error… every… single… time. And every single time, it’s due to a user either not reading, or deviating from the instruction set.

User error can be caused by various things:

  • the user is a moron
  • the user can't read
  • the instructions are unclear or too complex/confusing for the target users reading them

If different people all make mistakes when following some instructions, the first two possibilities become less and less probable.

We have already tutorials for relatively long and complex processes, but so far none has come here complaining that they did not understand or could not follow them https://lede-project.org/docs/guide-quick-start/factory_installation

Note how they are using simple formatting and inter-page links.

If you don’t want people using DokuWiki formatting, then change your wiki software.

This is a somewhat fair point, we did not have rules for wiki style/formatting until now, although the OpenWrt wiki did, at least theoretically.
I'm writing down a draft of the rules for the wiki content here, to give you an idea of what we want the wiki to be/look like https://lede-project.org/playground/wikirules

Thankfully, we don’t have to agree.

Actually, it would be best if we could at least reach some middle ground at least. You do have good understanding of a complex topic and dedication to keep it up-to-date, and we don't have a whole lot of people contributing to the wiki in general. I wrote or imported a good 70% of its current contents myself and I get notifications for any edit to any page, so I know.

As said above, I also think your article is confusing, and could be modified to be less so. I can do that myself too, I'm not asking you to do that.

If I recall correctly, it was precisely this type of attitude that caused LEDE to fork off to begin with.

It was more like a minority of guys not wanting to make ANY concession or ANY compromise even when confronted by others in their own team.

So the rest of the team forked and cut them out of the loop.

The same can happen here too, although it would look like someone banning you more than you making your own wiki page.

Here’s a bit of perspective:

Again, that does not show anything, only that people did not care back then. Many articles of OpenWrt wiki are in a total crap state and none cared either.
What matters is the number of people that asked for assistence in the forum because they could not follow/read/understand that guide.
I quite frankly don't know the numbers, I did not follow this whole thing closely.

I just know that I don't find it particularly easy to follow. And I'm a sysadmin with moderate linux experience.

1 Like

Yeah yeah this incident pointed out we actually need some rules for wiki contributions. :yum:

Articles should have an approval process, just like writing for any website.

So far we are doing decently with a screening process, someone (me or the others) see any edit as notifications and can take action.

1 Like

There are plugins available for some kind of approval process.
I checked them out quite a while ago and wasn't convinced that this would be a good solution.
Tell me if you want some details.

I agree, the current screening process is working.

I'm of the same opinion: Too much tabs, must be more linear.

@JW0914 From a normal user, you will get no feedback on a page, neither positive nor negative.
The absence of negative feedback on a page doesn't necessarily mean it's a good page.

Seems straightforward.

Another advantage of scroll-through vs tabs is it makes it much easier to print all the content.

2 Likes

The issue pointed out here is that the statements don't explain why it's deemed unsafe, or what these limitations are (= why should an user care), nor link to something else doing most of the talking (preferred since this is not specific to OpenWrt). Wikipedia editors would add a [citation needed] here.

One-line statements are not "explanations". For things that are not common knowledge, we need to have some reliable sources, your own opinion is not enough.

Could you @JW0914 please explain here or link some sources that explain better these statements? Even upstream OpenVPN documentation is using EasyRSA https://openvpn.net/index.php/open-source/documentation/miscellaneous/77-rsa-key-management.html so I don't see why should that be so bad.

Unfortunately, Alberto, it's like a game of pigeon chess.