mirror of
https://github.com/streetwriters/notesnook.git
synced 2026-09-01 19:49:54 +02:00
139 lines
7.1 KiB
Markdown
139 lines
7.1 KiB
Markdown
# Help docs — writing conventions
|
||
|
||
Every page on notesnook.com/help follows these. They cover accuracy, plan tags, SEO and linking.
|
||
|
||
## 1. Accuracy is non-negotiable
|
||
|
||
Never describe UI from memory. Every menu label, settings path, limit, default and plan gate must be traced to source in this monorepo before it is written:
|
||
|
||
- user-facing strings — `packages/intl/src/strings.ts`
|
||
- web/desktop UI — `apps/web/src/`, `apps/desktop/src/`
|
||
- mobile UI — `apps/mobile/app/`
|
||
- limits and plan gates — `packages/common/src/utils/is-feature-available.ts`
|
||
- behaviour, sync, encryption, retention — `packages/core/src/`
|
||
|
||
### Quote labels by key, not by hand
|
||
|
||
Don't type a label and hope it stays true. Write the **string key** and the build resolves it from the app's own catalogue:
|
||
|
||
```md
|
||
Click on `{{archive}}` renders: Click on `Archive`
|
||
Open `{{privacyAndSecurity}}` renders: Open `Privacy & security`
|
||
```
|
||
|
||
Keys come from `packages/intl/src/strings.ts` — the same catalogue the apps render from — so when someone renames a string in the app, every page quoting it updates on the next build. An unknown key **fails the build**; it never ships as a placeholder.
|
||
|
||
- Plural entries take a count: `{{notebooks:2}}`.
|
||
- `npm run strings` lists labels that could be keys but aren't; `-- --fix` rewrites the unambiguous ones.
|
||
- **Never add a string to `packages/intl` for the docs' sake.** If a label has no key — third-party UI, native OS text, a screen that isn't localized — write it as plain text.
|
||
|
||
If web and mobile differ, both go in the platform tabs. If you cannot verify something, leave it out and flag it — never guess.
|
||
|
||
## 2. Frontmatter
|
||
|
||
```yaml
|
||
---
|
||
title: Archive # short sidebar label, 2–3 words
|
||
pageTitle: How to archive notes… # optional: SEO <title>, ~60 chars
|
||
description: One sentence… # required, <160 chars, becomes the search snippet
|
||
keywords: # optional, real search phrases
|
||
- archive notes notesnook
|
||
schema: howto # optional: howto | faq | article (default article)
|
||
faqs: # required when schema: faq
|
||
- q: …
|
||
a: …
|
||
---
|
||
```
|
||
|
||
`schema: howto` turns the page's numbered steps into HowTo structured data automatically. `schema: faq` emits FAQPage structured data from the `faqs` list — the same Q&As must also appear in the page body.
|
||
|
||
## 3. Plan tags
|
||
|
||
Any feature that needs a paid plan is tagged inline, on the heading that introduces it:
|
||
|
||
```md
|
||
## Set a note to expire <PlanTag plan="pro" />
|
||
```
|
||
|
||
`plan` is the **lowest** plan that unlocks it: `essential`, `pro` or `believer`. Plans are cumulative — a `pro` tag means Pro and Believer. For platform-limited features add a note:
|
||
|
||
```md
|
||
## Pin a note to your notifications <PlanTag plan="pro" note="Android only" />
|
||
```
|
||
|
||
Verify the tier in `is-feature-available.ts` before tagging. Also state the consequence in prose where it matters ("free plans keep 100 versions per note"), and link to [Plans & limits](/plans-and-limits).
|
||
|
||
## 4. Article shape
|
||
|
||
```md
|
||
# Full human title
|
||
|
||
One or two sentences: what this is and why someone would want it.
|
||
|
||
## Task in imperative form
|
||
|
||
:::tabs key:platform
|
||
== Desktop/Web
|
||
|
||
1. …
|
||
|
||
== Mobile
|
||
|
||
1. …
|
||
|
||
:::
|
||
```
|
||
|
||
- One `# H1`, first line of the body.
|
||
- `##` per task, phrased as an action: "Archive a note", not "Archiving".
|
||
- Numbered steps, one action each, ideally ≤ 6.
|
||
- Close with the confirmation state — what the user should now see.
|
||
- `key:platform` is mandatory on platform tabs so the choice syncs sitewide. Labels: `Desktop/Web`, `Desktop`, `Web`, `Mobile`, `Android`, `iOS`, `Windows`, `macOS`, `Linux`.
|
||
- If a feature is missing on a platform, say so in that tab rather than omitting it.
|
||
|
||
## 5. Callouts
|
||
|
||
`::: info` context · `::: tip` shortcut · `::: warning` data loss or something irreversible · `::: danger` unrecoverable · `::: details` folded tangent.
|
||
|
||
Anything touching the vault, encryption, recovery or deletion must state plainly that **Notesnook cannot recover data or passwords for you**.
|
||
|
||
## 6. SEO
|
||
|
||
The help site already ranks #1 for high-intent queries like `import enex`, so each page is a landing page:
|
||
|
||
- **Write the H1 as the question a person types.** "How do I import notes from Evernote?" beats "Evernote importing".
|
||
- **Use real phrasings in `##` headings** — "Can I use it offline?", "Why is my note not syncing?" — they win featured snippets.
|
||
- **Answer in the first 40 words** after the H1. That paragraph is what Google quotes.
|
||
- **Never leave alt text empty.** Describe what the reader should look for: ``.
|
||
- **Every page ends with a `## Related pages` list** of 3–6 links with descriptive anchors (the home page, `/docs` and `/404` are exempt — they are already link lists) — "[backing up your notes](/backup-and-restore-notes-in-notesnook)", never "click here". This is what builds the internal link graph.
|
||
- **Link the first mention** of any concept that has its own page, in body text, with the concept as the anchor.
|
||
- **Add `<GetNotesnook />`** to pages people arrive at from search with buying intent — importers, comparisons, "how do I move from X" — placed after the instructions, never before them.
|
||
- Prefer one page that fully answers a question over three thin pages.
|
||
|
||
## 7. Internal linking clusters
|
||
|
||
Pages are grouped into clusters, each with a hub that links to every member and members that link back to the hub and sideways to siblings:
|
||
|
||
| Cluster | Hub |
|
||
| ------------------ | ------------------------------------------------------------- |
|
||
| Importing | [Importing notes](/importing-notes/) |
|
||
| Editor | [Editor toolbar](/rich-text-editor/rich-text-editor-toolbar) |
|
||
| Organization | [Notebooks](/organizing-notes/organize-notes-using-notebooks) |
|
||
| Privacy & security | [How is my data encrypted?](/how-is-my-data-encrypted) |
|
||
| Sync | [How sync works](/sync/how-sync-works) |
|
||
| Plans | [Plans & limits](/plans-and-limits) |
|
||
|
||
Any page that mentions a paid feature links to the plans hub. Any page that mentions encryption links to the encryption hub.
|
||
|
||
## 8. Things that are not allowed
|
||
|
||
- Undocumented guesses about UI, limits or plan gates.
|
||
- Version numbers in body copy ("as of v3.2").
|
||
- "Simply", "just", "easily", "seamlessly", "powerful".
|
||
- Telling the reader to contact support before the documented steps.
|
||
- Image paths that don't exist — leave `<!-- TODO: screenshot — … -->` instead.
|
||
- Renaming or moving an existing page (its URL is live and linked from the apps). Some pages are linked from inside the app itself via `packages/intl/src/strings.ts` — grep it before touching a slug.
|
||
- More than one `# H1` on a page, and `##`/`###` headings inside a `:::tabs` block. Headings in tabs are emitted once per tab, so they show up twice in the page outline with duplicate anchors.
|
||
- Unquoted frontmatter values containing `: ` — the YAML parser fails the build. Quote them.
|
||
- Alt text that describes nothing: `drawing`, a filename, or an unfilled template. Inline UI glyphs ("press the ⋯ button") are the one case where a short label is correct.
|