Skip to content

Commit 7cb55f5

Browse files
update style guide
1 parent 8fe54b4 commit 7cb55f5

File tree

1 file changed

+24
-11
lines changed

1 file changed

+24
-11
lines changed

.CONTRIBUTING/tutorials/STYLE_GUIDE.md

Lines changed: 24 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -37,25 +37,30 @@ tutorials/
3737
### Category Details
3838

3939
#### Polkadot SDK Tutorials (`polkadot-sdk/`)
40+
4041
- **Parachains**: Zero-to-hero guides, custom pallets, runtime development
4142
- **System Chains**: Asset Hub, Bridge Hub operations
4243
- **Testing**: Chain forking, spawning networks, benchmarking
4344

4445
#### Smart Contracts (`smart-contracts/`)
46+
4547
- **EVM Contracts**: ERC-20, NFTs, DeFi applications
4648
- **Native Contracts**: ink! smart contracts
4749
- **Demo Applications**: Complex application deployments
4850

4951
#### Interoperability (`interoperability/`)
52+
5053
- **XCM Operations**: Cross-chain messaging, asset transfers
5154
- **Channel Management**: HRMP channel operations
5255
- **Testing and Debugging**: XCM testing, replay, dry-run
5356

5457
#### dApps (`dapps/`)
58+
5559
- **Frontend Integration**: Wallet connections, chain interactions
5660
- **API Usage**: PAPI, Polkadot.js integrations
5761

5862
#### On-chain Governance (`onchain-governance/`)
63+
5964
- **Proposal Management**: Creating, voting, tracking proposals
6065
- **OpenGov Operations**: Delegation, conviction voting
6166

@@ -64,15 +69,14 @@ tutorials/
6469
### Target Audience Considerations
6570

6671
Before writing, determine:
72+
6773
1. **Target audience**: Beginners, intermediate, or advanced users
6874
2. **Prerequisites**: Required knowledge, tools, and setup
6975
3. **Learning objectives**: What users will accomplish
7076
4. **Category fit**: Ensure tutorial belongs in the appropriate category
7177

7278
### Writing Best Practices
7379

74-
**Note**: For comprehensive writing guidelines, refer to the [PaperMoon Documentation Style Guide](https://github.com/papermoonio/documentation-style-guide). The following are tutorial-specific essentials:
75-
7680
1. **Use active voice**: "You will build..." instead of "A blockchain will be built..."
7781
2. **Be specific**: Provide exact commands, file paths, and parameter values
7882
3. **Include context**: Explain why each step is necessary
@@ -104,6 +108,7 @@ categories: Category1, Category2, Category3
104108
### Common Categories
105109

106110
Use these standardized categories:
111+
107112
- `Basics`, `Parachains`, `Smart Contracts`, `dApps`, `Interoperability`
108113
- `Testing`, `Governance`, `System Chains`, `XCM`, `Runtime Development`
109114

@@ -137,6 +142,7 @@ images/tutorials/polkadot-sdk/parachains/zero-to-hero/set-up-a-template/
137142
### Navigation File Structure
138143

139144
Each directory contains a `.nav.yml` file defining navigation:
145+
140146
- `/tutorials/.nav.yml` - Main tutorials navigation
141147
- `/tutorials/[category]/.nav.yml` - Category-specific navigation
142148
- `/tutorials/[category]/[subcategory]/.nav.yml` - Subcategory navigation
@@ -154,6 +160,7 @@ nav:
154160
### Navigation Examples
155161
156162
**Main tutorials navigation** (`/tutorials/.nav.yml`):
163+
157164
```yaml
158165
title: Tutorials
159166
nav:
@@ -165,6 +172,7 @@ nav:
165172
```
166173

167174
**Category-specific navigation** (`/tutorials/polkadot-sdk/parachains/zero-to-hero/.nav.yml`):
175+
168176
```yaml
169177
title: Zero to Hero
170178
nav:
@@ -197,20 +205,16 @@ Store reusable code in the `.snippets` directory:
197205

198206
### Including Code Snippets
199207

200-
201208
```bash
202209
--8<-- 'code/tutorials/polkadot-sdk/parachains/setup.sh'
203210
```
204211

205-
206212
You can also use line numbers and include specific lines:
207213

208-
209214
```bash linenums="1"
210215
--8<-- 'code/tutorials/polkadot-sdk/parachains/setup.sh:10:20'
211216
```
212217

213-
214218
### Code Block Guidelines
215219

216220
- Always specify language for syntax highlighting
@@ -226,6 +230,7 @@ You can also use line numbers and include specific lines:
226230
### Language Tags
227231

228232
Common language tags to use:
233+
229234
- `bash` - Terminal commands
230235
- `rust` - Rust code
231236
- `javascript` - JavaScript/TypeScript
@@ -259,7 +264,6 @@ Common language tags to use:
259264
- **Desktop screenshots**: 1512px width, variable height
260265
- **Browser extension screenshots**: 400x600px
261266

262-
263267
### Image Syntax
264268

265269
```markdown
@@ -290,10 +294,6 @@ Before submitting, test your tutorial thoroughly:
290294
- [ ] All commands execute successfully
291295
- [ ] All downloads and installations work
292296
- [ ] Screenshots match current interface versions
293-
- [ ] Code examples compile and run
294-
- [ ] Expected outputs are produced
295-
- [ ] External links are functional
296-
- [ ] Tutorial works on different environments
297297

298298
### Common Testing Issues
299299

@@ -318,32 +318,43 @@ categories: [Categories]
318318
# Tutorial Title
319319
320320
## Introduction
321+
321322
[Context and objectives]
322323
323324
## Prerequisites
325+
324326
[Required knowledge and tools]
325327
326328
## Overview
329+
327330
[Architecture or process overview]
328331
329332
## [Action-Oriented Section Title]
333+
330334
### [Specific Task or Setup]
335+
331336
### [Another Specific Task]
332337
333338
## [Another Action-Oriented Section]
339+
334340
### [Implementation Task]
341+
335342
### [Testing or Verification]
336343
337344
## Testing and Verification
345+
338346
[Comprehensive testing instructions]
339347
340348
## Troubleshooting
349+
341350
[Common issues and solutions]
342351
343352
## Where to Go Next
353+
344354
[Advanced topics and related tutorials]
345355
346356
## Additional Resources
357+
347358
[External links and documentation]
348359
```
349360

@@ -383,6 +394,7 @@ Use these for important information:
383394
### Review Process
384395

385396
Before submission:
397+
386398
1. Self-review for completeness and accuracy
387399
2. Test on clean environment
388400
3. Check all links and references
@@ -394,6 +406,7 @@ Before submission:
394406
## Questions or Issues?
395407

396408
For additional help:
409+
397410
1. Check existing tutorials for examples
398411
2. Review the [main contributing guide](.CONTRIBUTING.md)
399412
3. Open an issue for clarification

0 commit comments

Comments
 (0)