You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Title, shorten if necessary, will be on sidebar
2
+
title: SEO-Rich Title That Matches Document Name and Path
3
3
description: A one sentence description.
4
+
sidebar_label: Title (match title if possible; can shorten if more than 2 lines, prefer 1 line)
4
5
sidebar_position: 5
5
6
keywords:
6
7
- keywords
@@ -9,20 +10,25 @@ keywords:
9
10
- cursor is great at this
10
11
---
11
12
12
-
# Complete Title
13
+
# Complete Title (Must Match Front Matter Title)
13
14
14
15
1-2 Paragraphs describing what the tutorial will teach, why someone might learn it, and if possible, a link to a live version of the app demoing the techniques and content taught.
15
16
17
+
**Important:** Do not add an H2 "Overview" heading. The overview text goes directly after the H1 title.
18
+
16
19
## Objectives
17
20
18
-
After completing this guide, you'll be able to:
21
+
Now that you've completed this tutorial, you'll be able to:
- Don't wordsmith these - clarity and directness are more important than variety
25
+
- It's okay if they're repetitive (e.g., "Construct X, Construct Y, Construct Z" is fine)
26
+
- Can use lower-level verbs if it makes sense for the learning goal
23
27
24
28
## Prerequisites
25
29
30
+
**Note:** Use canonical prerequisite text from the templates folder. When the import system is available, import prerequisites rather than copying and pasting.
31
+
26
32
### Next.js and Modern Frontend Development
27
33
28
34
This tutorial uses [Next.js]. You don't need to be an expert, but it's helpful to be comfortable with development using a current React framework. You'll be on your own to select and use a package manager, manage Node versions, and other frontend environment tasks. If you don't have your own preference, you can just follow along with us and use [Yarn].
@@ -31,24 +37,49 @@ This tutorial uses [Next.js]. You don't need to be an expert, but it's helpful t
31
37
32
38
This doesn't need to be exhaustive, but it should be comprehensive. It's a good place to outline what you're specifically **not** going to teach in this tutorial.
Text can go here. Usually it will be either an introduction to a long section with subsections, or a short section with no subsections that doesn't fit under a higher level.
37
43
38
-
### Subsection 1
44
+
### Document Length Guidelines
45
+
46
+
- Target size: ~500 lines (with each paragraph as a line, no manual line breaks)
47
+
- Maximum: 1000 lines
48
+
- Minimum: 200-300 lines (unless standalone like a simple configuration guide)
49
+
- If a tutorial exceeds 1000 lines, consider splitting into separate documents at logical breakpoints
50
+
51
+
### Subsection (H3)
39
52
40
-
Divide each part into appropriate categories.
53
+
Divide each section into appropriate categories.
41
54
42
-
**Avoid h4 and above**
55
+
**Recommended document structure:** Most documents should have 2-3 H2 sections with 2-5 H3 subsections in each.
43
56
44
-
## Part 2
57
+
**Avoid H4 and above** - If you're getting into H4, you're cutting the content into too small pieces.
45
58
46
-
More text goes here
59
+
## Another Descriptive H2 Heading
47
60
48
-
### Subsection 1
61
+
More text goes here. Use explicit, descriptive headings that tell the reader what they'll be doing in that section.
62
+
63
+
### Subsection (H3)
49
64
50
65
Continue as appropriate
51
66
67
+
## Tutorial Approach
68
+
69
+
**We are opinionated and provide one golden path.** We tell people one and only one specific way to do things in tutorials. This doesn't mean we can't teach multiple things - we can take learners through a journey - but we don't overwhelm them with choices when they're not informed enough to make decisions.
70
+
71
+
**Example:** In the getting started tutorial, we don't say "you could deploy this on testnet or emulator or mainnet." Instead, we say "first you are going to deploy this on emulator, here's how. Next you are going to deploy this on testnet, here's how."
72
+
73
+
**Why?** Learners coming to a tutorial don't know what they're doing - that's why they're at the tutorial. Cognitive friction from making decisions while learning prevents effective learning. If they have more experience, they can adapt our approach to their needs.
74
+
75
+
**Our opinionated choices:**
76
+
77
+
- Frontend: Next.js and Tailwind
78
+
- EVM: Wagmi
79
+
- Cadence: React SDK
80
+
81
+
**Rationale:** If they're a non-professional frontend developer writing smart contracts, they need exact instructions. If they're a professional frontend developer, they'll adapt it anyway and know how to do that.
82
+
52
83
## Style Guide
53
84
54
85
This section is a **guide** for the style and tone we use writing tutorials at Flow. It is **not** rigid or inflexible, but should be generally adhered to without specific reasons for exceptions.
@@ -59,32 +90,43 @@ Our standard is to achieve approximately 85% adherence or better before publicat
59
90
60
91
- Write content in a friendly and approachable tone, think business casual.
61
92
- Tutorials are less formal, docs are more formal, articles are in the middle.
93
+
-**Subheadings use sentence case** (not title case)
94
+
-**Use proper heading levels (H2, H3) for subheadings - do not use bold text alone as a heading**
95
+
- Use H2 for main sections
96
+
- Use H3 for subsections (can be used freely)
97
+
-**Recommended structure:** Most documents should have 2-3 H2 sections with 2-5 H3 subsections in each
98
+
- Avoid H4 and above
99
+
- Bold text is for emphasis within content, not for creating headings
62
100
- Avoid passive voice
101
+
-**Target eighth grade reading level** - We're teaching difficult and complicated things to people from many different backgrounds with many different first languages. We do not need to show off our vocabulary.
63
102
- Use **you** and **we** to speak directly to the learner
64
-
-Generally, use **you** when giving specific instructions to the learner to do on their own or giving them advice.
65
-
- Next, you'll need to implement a function that does X, Y, and Z. Try doing this on your own first.
103
+
-Use **you** when giving specific instructions to the learner or things they need to be aware of.
104
+
- Next, you'll need to implement a function that does X, Y, and Z.
66
105
- You might find that it's useful to index this property, but there is a performance cost.
67
-
- Use **we** when walking the learner through a task in a guided fashion, or when sharing an opinion (lead with **the team**).
68
-
- Next, we'll go step by step to implement the function to handle this task.
69
-
- We've found that a setting of 50 works best, but it's more of an art than a science.
106
+
- Use **we** when speaking as Flow Foundation (not "Flow Foundation" in third person - we're people talking to people).
107
+
- We recommend this approach.
108
+
- We found that a setting of 50 works best, but it's more of an art than a science.
109
+
-**Exception:** Only use "Flow Foundation" in third person for legal disclaimers when required by counsel.
110
+
- Avoid gerunds (-ing) when possible, but prioritize technical accuracy and clarity. If avoiding a gerund makes the text passive, uses 12 words instead of 5, or reduces technical accuracy, use the gerund.
70
111
- We do not use profanity.
71
112
- Released content should be free of spelling and grammar errors.
72
113
- We use US English spellings.
73
114
- We do **not** use manual line breaks.
74
-
- We are open and honest about our pros and cons as compared to other networks, but we are not harsh, critical, or insulting.
115
+
- We can be tactfully critical of other networks, but we must back up criticism with facts and evidence. We are not harsh or insulting.
75
116
- We use the Oxford comma.
76
117
- We use one space after periods.
77
-
- Use an autoformatter if you are unable to type only one.
78
-
- The site will render the same with 1 space or 2, so it is a moot point.
118
+
- Use an ESLint plugin for markdown that auto-formats your document
119
+
- The site will render the same with 1 space or 2, so it is a moot point
79
120
80
121
### Organization
81
122
82
-
- If you move a file, you **must** add a permanent re-direct to `vercel.json`.
123
+
- If you move a file, you **must** add a permanent redirect to `vercel.json`.
- This balances organization vs. convenience. We can re-evaluate if it gets out of control.
126
+
- Images can be stored either:
127
+
- Flat in the same folder as the document: `docs/build/cadence/guides/account-linking/example-app.png`
128
+
- In an `images` folder within the document's directory: `docs/build/cadence/guides/account-linking/images/example-app.png`
129
+
- Either approach is acceptable. Using an images folder is better organization, but having images flat in the folder is more convenient and encourages more image usage.
88
130
89
131
### Emphasis
90
132
@@ -94,7 +136,8 @@ Our standard is to achieve approximately 85% adherence or better before publicat
94
136
- Every instance of the term should **not** be highlighted. Only the first, the first in awhile, or when special attention must be called.
95
137
- Inline code samples or references, filenames, or interactive elements are surrounded by `backticks`.
96
138
- Next, call the `approve()` function.
97
-
- After filling out the form, click the `Submit` button.
139
+
- After filling out the form, click Submit (prefer "click Submit" over "click the `Submit` button" - more declarative and cleaner).
140
+
- UI interface elements can be in backticks to make them look like buttons: click the `Submit` button.
98
141
- The `.borrow()` function is a property used to...
99
142
- Create a file called `providers.ts` in the `app` folder.
100
143
- Function names must include the parentheses after the name but should **not** include parameters.
@@ -104,34 +147,45 @@ Our standard is to achieve approximately 85% adherence or better before publicat
104
147
-[Code Blocks] should be used for any segment of code longer than 15 characters.
105
148
- Supply the appropriate language
106
149
- Cadence is supported
107
-
- Always use `tsx` and `jsx` for TypeScript or JavaScript
108
-
- Use `zsh` for terminal text
150
+
- Always use `tsx` and `jsx` for TypeScript or JavaScript (they render TS/JS correctly too)
151
+
- Use `zsh` for terminal text (not `bash`) to match MacBook defaults
109
152
-[Admonitions] are used to highlight important sections of text.
110
-
-`tip` is used to share a tip or suggestion, or to remind the learner of something.
153
+
-**Important:** You must have a blank new line before and after the admonition text, otherwise the auto-formatter will break them.
154
+
-`tip` is used to share a tip or suggestion, or to remind the learner of something. **Use `tip`, not `note`** (note makes the box white and doesn't call enough attention).
155
+
-`reminder` is used to remind the learner of something.
111
156
-`info` is used to highlight unusual, confusing, or particularly important information.
112
157
-`warning` is used to highlight cases in which a mistake can cause confusion, frustration, or cost developer time.
113
-
-`danger` is used for anything in which a mistake can cause account compromise, loss of funds, key exposure, or any other type of permanent harm for developers or their users.
158
+
-`danger` is used for anything in which a mistake can cause account compromise, loss of funds, key exposure, or any other type of permanent harm for developers or their users. Use sparingly but appropriately - we work in a high-stakes environment where mistakes can cost millions of dollars.
114
159
115
160
### Links
116
161
117
162
- We use reference-style links using the text itself to identify the link.
118
163
- See lines 11 and 17 in this [markdown reference links] document.
164
+
- This makes the raw file more readable for editing and allows you to repeat links easily.
119
165
- Link the first reference to a function, property, tool, library, etc. and the first reference in the section in which it is used.
120
166
- This is critically important for links both within docs and to external sites
121
-
- Avoid unnecessarily linking directly to other networks' sites or properties unless citing a source.
122
-
- Internal links are relative and link to the file name. Docusaurus will sort itself and adding the `.md` or `.mdx` makes the link clickable in the editor.
- Don't link every instance - it quickly gets overwhelming and can hurt SEO if you have too many links.
168
+
- Avoid linking to other networks' sites unless:
169
+
- Citing a source or specific piece of information (e.g., "their own documents say that there is one single sequencer...")
170
+
- Making a critical point backed by facts
171
+
- Otherwise, don't make it easier for people to go to competitor information
172
+
- We strongly cross-link with products that work with our stuff (e.g., Wagmi docs, RainbowKit docs) and encourage them to cross-link with us.
173
+
- Internal links are relative and link to the **file name** (not the URL). Docusaurus will sort itself at build time, and adding the `.md` or `.mdx` makes the link clickable in the editor.
0 commit comments