Not everyone in Linxira's target audience is a Linux veteran — many potential users are students and researchers touching Linux for the first time. For them the documentation site is not a "reference tool" but "the last gate before the system becomes usable". The beginner's guide (/en/docs/newbie/) was designed for exactly that gate. This article reviews its page design decisions: what problem it solves, how the content was chosen, and how it divides labor with the existing documentation.
Visitors to the site do not necessarily know Linux. The people arriving might be a graduate student who wants a research environment, or an undergraduate just getting into open source — they do not know what a distribution is, what a package manager is, and some have never opened a terminal. For them, "a documentation site full of jargon" produces no help, only frustration.
And the docs' previous shape was unfriendly to newcomers: the entry points were bare Arch Wiki links plus post-install operational documents. Arch Wiki is extremely thorough, but it presumes readers who "already know how to use Linux"; the post-install documents presume readers who "already installed the system and know what they are doing". Both ends presume knowledge; neither covers the person using it for the first time.
What does "unfriendly" look like concretely? A newcomer opens a terminal, sees a wall of English output, and the first reaction is to close it rather than read it; opens an Arch Wiki entry and, faced with its density of jargon, concludes "this was not written for me". These reactions are not attitude problems — they are documentation presuming knowledge the reader does not have. The guide's job is to add the first rung of the ladder: starting from "what is a terminal", not from "how to configure Xorg".
The beginner's guide converges what "first use" requires into five sections, each answering one concrete class of question:
Ctrl+Alt+T), with a command table — pwd, ls, sudo pacman -Syu and other most-used commands explained one by one. It also gives a general strategy for errors: copy the English error output from the terminal into a search box.(简体中文) suffix on entries as the key clue.The selection principle: only answer the questions "first use" inevitably hits. No deep dive into package-manager internals, no primer on filesystem hierarchy — those belong to Arch Wiki and the deeper docs. The guide's goal is to get a newcomer through the minimal loop — open a terminal, update the system, look things up, type Chinese — in half an hour.
The command table is the typical product of that decision: it lists only the most-used commands (pwd, ls, sudo pacman -Syu, and a few more), one line each with a plain description of what it does, no syntax rules explained. "What to do when an error appears" follows the same minimal-loop principle — not a methodology course, just one action that always works: copy the English error output into a search box. Together, these two cover the 90% of situations a newcomer meets in the first days.
The Arch Wiki section deserves its own note, because it is the part that most directly teaches a skill rather than a fact: recognizing the (简体中文) suffix, switching the language menu, and searching within the page are three small habits that turn an intimidating resource into an answer source. Teaching the habit of looking things up — rather than handing over a list of pre-answered questions — is what lets newcomers survive beyond the first week without a guide at their side.
Within the Chinese environment section, the input method gets the most attention, because it is the classic newcomer killer: after install you discover you cannot type Chinese, the solutions you find are all over the place, and every change makes things worse. The guide reduces troubleshooting to three steps:
1) Confirm it is installed — run sudo pacman -S fcitx5 fcitx5-chinese-addons fcitx5-configtool to make sure the input framework, Chinese addons, and configuration tool are all present.
2) Enable Pinyin — System Settings → Input Method → Add Input Method → choose "Pinyin"; the switching shortcut is Ctrl+Space.
3) Still broken → read the diagnostic report — run fcitx5-diagnose | head -n 100 and paste the output to the community or into a search. Linxira uses Fcitx5 uniformly; do not install other input frameworks like ibus at the same time to avoid conflicts.
Two easy-to-miss additions are also in the doc: if you installed a non-KDE desktop like GNOME yourself and the input method does not take effect, write three environment variables into ~/.xprofile and restart the session — export GTK_IM_MODULE=fcitx, export QT_IM_MODULE=fcitx, export XMODIFIERS=@im=fcitx; if the locale is not active, uncomment the zh_CN.UTF-8 UTF-8 line in /etc/locale.gen with sudo nano /etc/locale.gen, then run sudo locale-gen.
The logic of these three steps: first confirm "is it there", then confirm "is it enabled", and only then move to "diagnose". Every step is self-contained and executable — newcomers do not need to understand the underlying mechanism; following the steps locates the problem.
The ordering of the steps is itself troubleshooting training: the vast majority of "input method does not work" cases are actually "not installed" or "not enabled", and the first two steps resolve them; only the rare remainder needs the third step's diagnostic report. Had we led with the report, most of its output would be noise to a newcomer. The division makes the correspondence between "what to check" and "why to check it" obvious at a glance, and keeps simple problems simple.
The beginner's guide is not a rewrite of all documentation; it only covers "from zero to first usable". The division with existing docs is:
The three form a funnel: the beginner's guide carries the most people to a "usable" starting point, quick start picks them up for post-install configuration, and the specialized docs serve the few who want to go deeper. Each document only answers the questions of its own layer; none dilutes the others.
The division has a hidden benefit: the documents never develop two competing narratives for "those who know" and "those who do not". The beginner's guide says "update the system with sudo pacman -Syu", quick start uses it directly, and the desktop docs do not re-explain it — the same command is introduced exactly once across the whole documentation set, and everything else references it. For maintainers this means changing a term or command in one place does not require synchronizing three documents.
Good content is not enough — newcomers have to actually reach it. Three integration points:
The three entries cover three ways of arriving: browsing in from the sidebar, clicking in from the home page navigation, or opening quick start after installing and being guided back. Whatever entry a newcomer takes, one step gets them to the right place.
The integration itself embodies a design principle: newcomers should not need to understand the documentation structure to find the guide — the structure serves them instead of requiring them to understand it. The sidebar puts the guide first, the navigation card puts it first, and the notice bar steers back the people who walked through the wrong door; with these three guarantees, "could not find the entry" stops being a possible failure mode.