Why do guides focus on technical details rather than how to use things?

Talk about Documentation
1

Hello Follks,

i wonder why almost openwrt guides are not written like an playbook and concentrated on the user and not so much on the technical side, im a rookie and i wish i had sth. like and my explained a little bit more eli5. A good example is the playbook from the salesforce crm.

Core Concern

  • OpenWrt documentation and guides are too technically focused.

  • They often skip user-centric use cases and the pre-configuration phase.

What’s Missing

  • Clear explanation of why and when to apply configurations.

  • Guidance tailored to real-world services (e.g., HTTP, FTP), not just technical details.

Requested Improvement

  • Documentation structured like a playbook, not a reference manual.

Desired Playbook Structure

  • Thinking Order

    • What questions to ask first before configuring a service.

  • Configuration Mindset

    • How to think through setting up a service (HTTP, FTP, etc.).

  • Rules & Constraints

    • Key principles and rules that must be followed.

  • Practical Examples

    • Simple, concrete examples showing:

      • Where to begin

      • Step-by-step progression

      • Clear and easy-to-understand explanations

Regards

1 Like
2

Tell us more hat is the purpose of it?

FYI: ELI5 is AI text generator that tries to do what you demand....

3

Isn’t this a contradiction? A router is a complex beast, since there are a lot of different setups and thus there are loads of different configurations possible. It simply is impossible to write a “playbook” for every scenario.
But hey, if you want to improve the documentation you are free to do so.

3 Likes
4

5yo generally can not read, so no guide is a good guide, just give them ice cream :smiley:

2 Likes
5

because installation often is the tricky part ?
it's where you can brick a device if you get it wrong, same won't happen if you make some random mistake configuring it.

2 Likes
6

In my opinion (based on observations), the wiki has pages that are written at different 'levels'.

For example, some are written in such a way as to guide the user through the configs/changes in a user-centric way that allows the user to see both the how and why -- this is useful for those learning OpenWrt and/or specific networking concepts for the first time. For example, the bridged-AP and DSA mini tutorial go through a lot of the explanations of what is happening.

On the other side are either more advanced config operations such as the automated Wiregaurd setup or the extroot process which assume a bit more fundamental knowledge and focus mostly on the process (via script or commands on the CLI).

While there can be value in having both the full explanation and the 'run the playbook' pages, the different topics are often targeting different audiences (novice vs experienced).

Also, as stated earlier, actual playbooks (for true step-by-step implementation with no thinking/interpretation required) may not work for some types of setups when you consider the vast diversity of both supported hardware and individualized configs/environments.

All of that said, if there are specific things that you feel should be written for different audiences (for example, a bridged AP "playbook" that just does through the process but doesn't explain anything; or a wireguard "explainer" that is useful for beginners to expand their knowledge with the 'why'), feel free to write up those pages and add them to the wiki.

5 Likes
7

@moejoe it is hard to follow. Please show an article without principle and suggest one.

2 Likes
8

I like the idea. Now that you have gone through it, can you write two or three example guides for the next person?

Maybe laying the foundation first, then branch out.

  • Stages of a home network and why you want them
  1. all-in one wifi-router
    which channels to choose 1/5/9/13 or 1/6/11? What about my neighbours?
    add Cake after testing and confirming bufferbloat
  2. add guest- or iot-network - what problem do they solve?
    where does my TV go? Can guests show stuff on the family TV from their phone / laptop?
  3. add access points with VLAN and roaming
    how many
    why ist AX nice for 2.4GHz but AC good enough for 5GHz?
    Should I lower 2.4GHz power or just turn it off on every second AP?
    What tools are there to make my life easier if I want to keep multiple APs in sync?
  4. do I want a dedicated mangement VLAN? How do I implement it?

Then a guide for each step.

1 Like
9

Only this one works in practice, yes in ETSI regions the former would be more ideal on paper, but given the prevalence of commercial routers using 1/6/11 regardless, you can only follow suit (or make it worse for yourself and your neighbours). ...and HT40 kind of renders this moot anyways.

1 Like
10

Sorry, but so they should be. They are primarily "Technical Reference Documentation", not "Beginner's Guides".

There is of course a place for the Beginner's Guide, but in practice they are few and far between, because it will always fall to the developer, at least initially, to provide technical documentation.

Once a reader with any real interest in what they are doing has read a Beginner's Guide, they will want to, at least, read more in depth on the subject.
If they do not have such interest, there is a strong case for them to stick with the manufacturer's firmware and to read the Quick Start Guide that usually comes in the box.

If you want to write the "playbook", to be qualified to do so, you must first gain a pretty full understanding of the "Technical Documentation" before starting.

If you are up for this, all well and good. Pick a subject and take a really deep dive.
Push it to Github so others can review it as you go as well as make suggestions.

When your Version 1.0.0 Documentation is ready, create your wiki page.

This is not trivial, but for the right type of person can be an interesting project.

5 Likes
11

@moejoe awaiting your response.

12

Note, my english isnt the best so i use ai as an helper, but my ideas are in the Text.

Suggestions to Make OpenWrt Documentation More Beginner-Friendly

First of all, thank you all for your valuable feedback. No offense is intended — I truly appreciate the work that goes into OpenWrt documentation and development.

I understand that changing an established documentation style can require significant effort, and not everyone may agree with a different approach. That’s completely fine. I also want to apologize in advance: I don’t have the technical expertise to fully create these materials myself. These are simply ideas and suggestions for discussion.

Below are some possible approaches and guiding principles.

Core Ideas for Beginner-Friendly Documentation

1. Use More Visual Explanations

A picture often explains more than 1,000 words.

Instead of relying only on text, documentation could include:

  • Topology diagrams

  • Mind maps

  • Flow charts

  • Visual network layouts

For example:

  • A firewall could be shown as a diagram where rules are like branches in a mind map.

  • Network zones could be visualized with clear arrows showing traffic flow.

Visual structure helps beginners understand relationships between components much faster than dense text alone.

2. Use Analogies to Explain Technical Concepts

Technical concepts can feel overwhelming to non-technical users. Analogies help bridge that gap.

For example:

  • Firewall = Airport security
    Every packet is like a passenger.
    Some are allowed through, some are checked, and some are denied entry.

  • Router = Traffic control center
    It directs traffic to the correct destination.

  • Network zones = Different areas in a building
    Public lobby (WAN), private office (LAN), restricted archive room (guest network or isolated VLAN).

These comparisons make complex ideas easier to understand for people with little or no technical background.

3. Start from the User’s Goal — Not the System’s Structure

Documentation is often written from the developer’s perspective:

  • “Here is how the system works.”

  • “Here are the components.”

But beginners usually think differently:

  • “I want to connect a device.”

  • “I want my NAS accessible.”

  • “I want Wi-Fi for guests.”

  • “I want my network to be secure.”

The documentation structure could follow real user goals instead of technical modules.

4. Apply “Theory of Mind”

Try to think from the beginner’s perspective:

  • What does the user actually want?

  • What are they afraid of breaking?

  • What terms confuse them?

  • What assumptions are we unconsciously making?

5. Think More Like a Consumer-Oriented Product

From a business or user-experience perspective:

  • Reduce friction.

  • Reduce cognitive overload.

  • Guide users step by step.

  1. Create the documentation in a way that covers as much of the core setup as possible by default.

    Then, for more specific use cases or advanced configurations, provide links to additional documents that users can follow depending on their individual needs.

Example: A User-Level Documentation Approach

Scenario

A typical beginner user wants to:

  • Connect a NAS to archive movies and files

  • Get internet Access from laptops and smartphones

Step 1: Draw an Simple Network Diagram or an Mindmap

Include a visual:

Internet → Router → LAN → NAS + Clients

**
Step 2: Describe the Main Concept of the Openwrt Router and add some easy topograms/flows:
Can be like sth in this way:**

The Main Concept

OpenWrt separates the network into clear building blocks:

  • Interfaces → Where traffic enters or leaves

  • Zones → How trusted that traffic is

  • Firewall rules → What traffic is allowed

This modular structure makes everything flexible but still logically organized.

Toplogie:

OpenWrt Router
│
├── Interfaces
│ ├── WAN (Internet connection)
│ ├── LAN (Local network)
│ └── Optional (Guest / VLAN)
│
├── Zones (Security Levels)
│ ├── WAN Zone (Untrusted)
│ └── LAN Zone (Trusted)
│
└── Firewall Rules
├── LAN → WAN (Allow Internet access)
├── WAN → LAN (Block by default)
└── LAN → LAN (Allow internal communication)

Flow Example:

Internet
↓
[ WAN Interface ]
↓
[ WAN Zone ]
↓
[ Firewall Rules ]
↓
[ LAN Zone ]
↓
[ LAN Interface ]
↓
Your Devices

**
Step 3. Which Services/Software i need ?**

Explain what an service is mainly and then which service u need ( for example nas: samba etc.) and may which setings u have to set specifically.

For example like this:

What is a Service in OpenWrt?

A service is just something extra your router can do.

Think of your router like a small computer:

  • By default, it just connects devices to the internet.

  • A service adds a new feature, like:

    • NAS/Shared storage → lets your devices access files on a USB drive

    • VPN → lets you connect securely from outside your home

    • Ad-blocker → blocks unwanted ads

    • Dynamic DNS → keeps your home network reachable from the internet

In short: A service is a program that runs on your router and does something useful for your network.

NAS on OpenWrt:

A NAS lets you share files on your network (PCs, phones, etc.).

:one: Needed Services

  • Samba (SMB) → luci-app-samba (for Windows/Mac/Linux)

  • Optional FTP → luci-app-vsftpd

:two: Install in LuCI

  1. Go to System → Software

  2. Click Update lists

  3. Search and Install the service (samba36-server + luci-app-samba)

:three: Configure

  1. Go to Services → Samba

  2. Choose folder to share, set permissions, add users if needed

  3. Save & Apply

:four: Enable & Start

  1. Go to System → Startup

  2. Enable and Start samba

Firewall Rules:
Explain what the firewall is with an analogy like the Airport Example above.

What u need for rules for NAS ?:

What Firewall Rules You Need for a NAS

To safely share files on your network:

  1. Allow LAN → LAN

    • All devices inside your home network need to talk to the NAS.

  2. Block WAN → LAN

    • Don’t let the internet directly access your NAS (security risk).

  3. Optional: Allow specific ports for external access

    • Only if you want remote access (like FTP or VPN).

Default OpenWrt usually blocks WAN → LAN automatically. The main thing is ensuring LAN devices can reach the NAS.

:two: How to Implement Firewall Rules in LuCI

Step 1: Open Firewall Settings

  1. Log in to LuCI

  2. Go to:

Network → Firewall

Step 2: Check Zones

  • Make sure your LAN zone is set as trusted

  • WAN zone should stay untrusted

Step 3: Add a Rule (if needed)

  1. Go to Traffic Rules → Add

  2. Example for allowing LAN → NAS:

  • Name: LAN to NAS

  • Source zone: LAN

  • Destination zone: LAN

  • Destination port: leave blank (or specify SMB: 445)

  • Action: Accept

  1. Save & Apply

Step 4: Optional External Access

  • Only if you need FTP or VPN access from the internet

  • Open specific ports (e.g., FTP: 21)

  • Always restrict to trusted IPs if possible

Summary

To make OpenWrt documentation more beginner-friendly:

  • Use more visuals

  • Use real-life analogies

  • Start from user goals

  • Avoid assumptions about prior knowledge

  • Structure guides around real-world use cases

  • Separate beginner paths from advanced explanations

These are only ideas for discussion, not criticism and its far from complete. The goal is simply to make OpenWrt more accessible to a broader audience.

Thank you again for all your work and contributions.

And i hope that i could s.o give some impressions for his own creating some HowTos’s, if not its also okay.

best regards

13

Your clanker slurped very old books , ftp nowadays is well fertilizing grass from below.

ref: https://blog.mozilla.org/security/2021/07/20/stopping-ftp-support-in-firefox-90/

This could land one in hamdcuffs some legal mess

Explaim, from a non-technical perspective, how your 5yo user got thrir hand on movies.

14

Just use your ai chatbot to create the guides you demand in your language. :light_bulb:

5 Likes
15

Based on the content, it would seem to be more AI ideas than yours....

1 Like
16

@moejoe it is imperative that you provide original textss in original language, because the English "translation" is full of cow droppings does not sound right

17

Hi @moejoe
you seem to be on the classical road to free and open software participation in that you noticed room for improvement in a corner of a project you care about. Excellent! Especially since documentation can always be improved :wink: and improving it is a bit of a thankless job.
The next step is how to achieve some meaningful change...
You essentially have your own time and effort to comandeer, so the sky is the limit here, others might or might not contribute depending on how they want to invest their own time, that is normal and expected#.
You already conceptually identified an issue that you would like to address, good. You are also a bit hesitant as you seem to feel that you lack some domain knowledge and expertise to improve some of the issues. Here is my offer, you pick a single specific document with limited scope that you want to improve or maybe even better create from scratch and I promise to help you with the missing expertise, either because I can contribute said expertise, or more likely by helping you research the missing information, but we can start with expertise gaps, as long as we clearly and explicitly mention which sections need an expert pass over.
Regarding AI, let's be cautious and if at all only use it for translation and maybe smoothing the final language, let's not fall into the temptation to use it to fill in our expertise gaps (modern LLMs are marvelous at what they do, but need expert supervision, and that means we can not use them where we lack the expertise to check their output for correctness).
My time is limited though, so I will promise to help, but with no timing guarantees, there are weeks where work leaves no spare time and others it does.
So gentleman, start youg engine and begin by defining the exact piece of documentation we should tackle first and come up with a plan what to do exactly.

#) This means however that some grand strategy ideas how the whole project should address issues like documention are essentially unachievable as you have no real control over others... what you can do however is create your own documentation as good examples for others.

5 Likes
18

I understand the core problem as I have an education in Design (including UI and UX) and this tends to be an issue with most open-source projects. There is simply not enough manpower to polish documentation or to make things user-friendly. Most things are purely developer focused because that is the main user-base and people working on it.

@moejoe I would love to see you take some initiative to lay out the framework for how to do this and then people may see it worthwhile to contribute their time. Same for me, I would love to help make OpenWrt accessible and easier to use for more people.

2 Likes