resolve comments

Author: todortodorovic

.CONTRIBUTING/tutorials/.CONTRIBUTING.md

@@ -34,6 +34,7 @@
 ## Choose Your Contributing Path
 
 ### Team-Assisted Path (Recommended)
+
 **Allow the Polkadot Docs team to handle formatting and style**
 
  **Benefits:**
@@ -52,12 +53,14 @@
 **Required:** You must read the [STYLE_GUIDE.md](STYLE_GUIDE.md) to understand all requirements. The difference is that with the team-assisted path, they will have the bandwidth to handle the review process.
 
 ### Self-Managed Path
+
 **Handle all formatting and style requirements yourself**
 
  **Full control** over your tutorial format and style
  **More review rounds** - you must fix all style issues
  **Required reading:** [STYLE_GUIDE.md](STYLE_GUIDE.md)
- **For expedited review:** Also read the PaperMoon Documentation Style Guide
+ **For expedited review:** Also read the [PaperMoon Documentation Style Guide](https://github.com/papermoonio/documentation-style-guide).
+
 
 ---
 
@@ -78,12 +81,25 @@ categories: Category1, Category2
 
 ### 2. File Structure (Required)
 
+Once you've defined your tutorial path, ensure images and code snippets follow the same structure.
+
+**Tutorial file:**
 ```
 tutorials/[category]/[subcategory]/[tutorial-name].md
+```
+
+**Supporting files:**
+```
 images/tutorials/[category]/[subcategory]/[tutorial-name]/
 .snippets/code/tutorials/[category]/[subcategory]/[tutorial-name]/
 ```
 
+**Image naming convention:**
+```
+images/tutorials/[category]/[subcategory]/[tutorial-name]/[tutorial-name-01.webp]
+```
+Where the number will be 01, 02, 03, etc.
+
 ### 3. Navigation Update (Critical)
 
 **Must update `.nav.yml` files** or your tutorial won't appear in the left-side menu:
@@ -118,7 +134,10 @@ images/tutorials/[category]/[subcategory]/[tutorial-name]/
 ## Prerequisites
 - [Required knowledge/tools]
 
-## Step 1: [Action]
+## [Action-Oriented Section Title]
+[Instructions with commands]
+
+## [Another Action-Oriented Section Title]
 [Instructions with commands]
 
 ## Verification
@@ -128,6 +147,8 @@ images/tutorials/[category]/[subcategory]/[tutorial-name]/
 [Related tutorials]
 ```
 
+**Note:** Use action-oriented section titles (e.g., "Environment Setup", "Client Configuration") instead of generic "Step 1", "Step 2" format.
+
 ## Image Requirements
 
 - **Format**: `.webp` only  
@@ -140,6 +161,7 @@ images/tutorials/[category]/[subcategory]/[tutorial-name]/
 
 ## Submission Checklist
 
+- [ ] Tutorial follows a clear storytelling structure with logical flow
 - [ ] Metadata complete
 - [ ] Working code tested
 - [ ] Images in `.webp` format

.CONTRIBUTING/tutorials/STYLE_GUIDE.md

@@ -71,20 +71,15 @@ Before writing, determine:
 
 ### Writing Best Practices
 
+**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:
+
 1. **Use active voice**: "You will build..." instead of "A blockchain will be built..."
 2. **Be specific**: Provide exact commands, file paths, and parameter values
 3. **Include context**: Explain why each step is necessary
 4. **Use consistent terminology**: Follow established Polkadot vocabulary
-5. **Provide alternatives**: When multiple approaches exist, mention them
-6. **Add warnings**: Use `!!!warning` for important caveats
-
-### Tone and Style
-
-- Write in second person ("you will", "your application")
-- Use clear, concise sentences
-- Break up long paragraphs
-- Use bullet points for lists and options
-- Number steps for procedures
+5. **Tutorial language**: Use "you" when addressing the reader, "we" when working through steps together
+6. **Structure clearly**: Use bullet points for lists, number steps for procedures
+7. **Break up content**: Keep paragraphs concise and readable
 
 ## Metadata Requirements
 
@@ -220,7 +215,8 @@ You can also use line numbers and include specific lines:
 
 - Always specify language for syntax highlighting
 - Include file names when showing file contents
-- Use `!!!tip` to explain complex code sections
+- Use `!!!tip` sparingly to explain complex code sections (avoid admonitions when possible)
+- For collapsible code sections, use: `??? code "<Title>"`
 - Test all code examples before submission
 - Include expected outputs where relevant
 - **Always specify dependency versions** in installation commands
@@ -257,6 +253,7 @@ Common language tags to use:
 - Update screenshots when UI changes
 
 #### Image Dimensions
+
 **Important**: Use these specific dimensions to avoid rework during review:
 
 - **Desktop screenshots**: 1512px width, variable height
@@ -329,13 +326,13 @@ categories: [Categories]
 ## Overview
 [Architecture or process overview]
 
-## Part 1: [Section Title]
-### Step 1: [Substep]
-### Step 2: [Substep]
+## [Action-Oriented Section Title]
+### [Specific Task or Setup]
+### [Another Specific Task]
 
-## Part 2: [Section Title]
-### Step 1: [Substep]
-### Step 2: [Substep]
+## [Another Action-Oriented Section]
+### [Implementation Task]
+### [Testing or Verification]
 
 ## Testing and Verification
 [Comprehensive testing instructions]

.CONTRIBUTING/tutorials/templates/README.md

@@ -129,7 +129,7 @@ Feel free to add sections relevant to your tutorial:
 Replace template code with your specific examples:
 - Use real, tested code snippets
 - Include error handling where appropriate
-- Show expected outputs
+- Show expected outputs (use `termynal` element for terminal outputs)
 - Provide alternative approaches when relevant
 
 ## Questions and Support

.CONTRIBUTING/tutorials/templates/polkadot-sdk-template.md

@@ -24,7 +24,7 @@ Before starting, ensure you have:
 - Basic understanding of [required concepts]
 - [Tokens/accounts if needed]
 
-## Step 1: Project Setup
+## Environment Setup
 
 [Set up the development environment and project structure]
 
@@ -33,6 +33,9 @@ Before starting, ensure you have:
 git clone -b INSERT_TAG_HERE https://github.com/paritytech/polkadot-sdk-parachain-template.git parachain-template
 ```
 
+!!! note
+    Replace `INSERT_TAG_HERE` with the actual tag or branch of the parachain template you want to use (e.g., `polkadot-stable2412`).
+
 Expected output:
 ```
 [Show expected terminal output]