Wiki Conventions

Wiki conventions

This page defines how NyxOS wiki articles are written. Follow it when editing an existing page or adding a new one, so the wiki reads as one document rather than a pile of notes.

See also: Contributing, Home

Article structure

Every article follows the same skeleton:

# Title

One or two sentences stating what the subsystem is and what it does.
No marketing language.

See also: [[Related]], [[Pages]]

## Overview / Concepts        (what it is)
## Reference                  (tables: constants, fields, options)
## Procedures                 (how to do things)
## Troubleshooting            (symptom → cause → fix)
## See also
## External resources         (specs, RFCs, upstream docs)

Reference pages may omit Procedures; HOWTO pages may omit Reference. Every page carries the See also line near the top and a See also section at the bottom.

Prompts

NyxOS has two shells and the host has one. Which prompt appears tells you where a command runs.

Prompt	Where
host $	Your development machine (Linux, WSL, or PowerShell)
nyx>	The NyxOS kernel shell — serial console or GUI terminal
sh$	The NyxOS userspace shell, /sh.elf

Never paste the prompt itself when copying a command.

Code blocks

Every non-trivial block gets a caption line stating what it is, in bold, immediately above it. This is the closest GitHub-flavored Markdown gets to Gentoo's CODE/FILE templates.

CODE — Building the kernel

host $ make -C kernel

FILE — kernel/Makefile (excerpt)

CFLAGS = -std=gnu99 -ffreestanding -Os -Wall -Wextra

Rules:

• Use bash for host commands, c for C, make for makefiles, asm for assembly, and no language tag for terminal output or NyxOS shell sessions.
• Show real output. If output is trimmed, say so with […].
• If a transcript came from a specific build, state which one in the caption.

Admonitions

Use GitHub alert syntax. Do not invent other kinds.

Note

Neutral information the reader may not know. Use sparingly — most facts belong in body text.

Tip

A shortcut or a better way of doing the thing just described.

Important

Something the reader must do, or the procedure will not work.

Warning

Something that can lose data, corrupt a disk image, or wedge the machine.

Caution

A security consequence.

Tables

Tables are the default form for reference material. Every constant, field, flag, option and error code belongs in a table with its value and its meaning, not in prose.

Escape a literal pipe inside a table cell as \|.

Facts and verification

• Every constant, path, syscall number and default stated in this wiki must be checkable against the source tree. Cite the file, e.g. MAX_INODES (kernel/vfs.c).
• When a number changes in the source, the wiki is wrong until it is updated. AGENTS.md makes this a commit requirement — see Contributing.
• Do not document intentions. If a feature is planned but not implemented, either omit it or put it under an explicit Known limits heading.
• Prefer stating a limitation plainly over implying completeness.

Voice

• Present tense, active voice. "The scheduler picks the next task", not "the next task will be picked".
• No exclamation marks, no "simply", no "just", no "obviously".
• Bugs are worth documenting when they explain why the code looks the way it does. The wiki keeps several of these deliberately.
• British or American spelling is acceptable; be consistent within a page.

Page naming

GitHub Wiki maps a page title to a filename by replacing spaces with hyphens. [[Boot Process]] resolves to Boot-Process.md.

• Titles are sentence case: Memory management, not Memory Management, except where the existing page set already uses title case — match the neighbours.
• HOWTO pages are named HOWTO <task>, e.g. [[HOWTO Add a system call]].
• Every new page must be added to _Sidebar.md, or it will be unreachable.

Linking

• Link the first mention of another subsystem in a section, not every mention.
• Use a piped link when the sentence needs different words: [[Selene Browser|Selene]].
• External links go in the External resources section as a list, with the publisher named.

Checklist before committing

• Every stated fact checked against the source tree
• Page added to _Sidebar.md if new
• All [[links]] resolve to real pages
• Code blocks have captions and language tags
• See also present at top and bottom
• README, docs/ and AGENTS.md updated if the change affects them

See also

• Contributing — development workflow and the commit rule
• Home — wiki index

External resources

• GitHub Flavored Markdown spec — GitHub
• Alerts syntax — GitHub Docs