#Page templates

Every portal page is exactly one type. Mixing types is the most common failure: an explanation buried in a tutorial loses the learner, and an exhaustive option list inside a how-to hides the path that works. If your content wants to be two types, write two pages and link them.

#How to pick the type

In one line: learning by doing is a tutorial; solving a task is a how-to; looking up a fact is reference; asking "why" is explanation; starting from an error message is troubleshooting.

#Tutorial

You are teaching, and you are responsible for the learner reaching the end.

• Open with the destination: "In this tutorial we are going to…", and show the end result.
• A visible result after every step.
• One path only: no options, no alternatives, no branches.
• Minimum explanation; link to the background instead of including it.
• Tested end to end, repeatable, with no irreversible steps.

#How-to

The reader is already competent and has a task.

• The title names the task literally: "How to X", never "Integrating X".
• Action and only action. No teaching, no digressions.
• Ordered by the real workflow.
• Not exhaustive: the full option list lives in reference, linked.
• End with a verification section: how to confirm it worked.

#Reference

Facts to look up.

• Austere, neutral, factual. No instructions and no opinions.
• The structure mirrors the code or the product, so navigating matches using.
• Uniform format across pages: readers find each thing in the same place.
• Examples illustrate; they do not teach.

#Explanation

Read away from the keyboard.

• The why: design decisions, constraints, history, trade-offs.
• Alternatives and differing viewpoints belong here, and only here.
• No step-by-step instructions and no reference dumps.

#Troubleshooting

• The title is the symptom as the reader sees it, with the exact error text.
• One section per distinct cause.
• Close with the verification that the fix worked.

#Rules that apply to every type

• Most important information first: in the page, in each section, in each sentence.
• Short sentences, active voice, present tense. "The command creates the file", not "will create".
• Instructions start with an imperative verb, and the condition comes before the action: "If you use pnpm, run…".
• Never "simply", "you just have to", "easily" or "obviously".
• Numbered list for a sequence; bullets for an unordered set; a table for value pairs.
• Every code sample is real and runnable. No foo or bar, no real credentials.
• Link text names its destination. Never "here" or "more information".
• Headings in sentence case, no trailing punctuation, never skipping levels.
• One concept, one term, across the whole portal.
• After a significant step, show the expected output: "You should see: …".

#Related

• How to contribute to the portal — the full flow up to the MR