content-standards.md
1 # Content Standards and Templates 2 3 This document defines the standards, templates, and guidelines for creating and maintaining Planar documentation. All contributors should follow these standards to ensure consistency and quality. 4 5 ## Content Categories 6 7 ### Getting Started 8 **Purpose**: Guide new users from installation to first success 9 **Audience**: Complete beginners to Planar 10 **Tone**: Encouraging, step-by-step, assumes no prior knowledge 11 **Success Criteria**: User can complete tasks independently 12 13 ### Guides 14 **Purpose**: Explain concepts and workflows in depth 15 **Audience**: Users with basic Planar knowledge 16 **Tone**: Educational, comprehensive, practical 17 **Success Criteria**: User understands concepts and can apply them 18 19 ### Advanced 20 **Purpose**: Cover complex topics and customization 21 **Audience**: Experienced users and developers 22 **Tone**: Technical, detailed, assumes expertise 23 **Success Criteria**: User can implement advanced features 24 25 ### Reference 26 **Purpose**: Provide complete API and configuration documentation 27 **Audience**: All users looking up specific information 28 **Tone**: Precise, comprehensive, searchable 29 **Success Criteria**: User finds exact information needed 30 31 ### Troubleshooting 32 **Purpose**: Help users resolve problems quickly 33 **Audience**: Users encountering specific issues 34 **Tone**: Solution-focused, systematic, empathetic 35 **Success Criteria**: User resolves their problem 36 37 ## Writing Standards 38 39 ### Language and Style 40 41 #### Voice and Tone 42 - **Active Voice**: "Configure the strategy" not "The strategy should be configured" 43 - **Present Tense**: "The function returns" not "The function will return" 44 - **Direct Address**: "You can configure" not "One can configure" 45 - **Positive Framing**: "To enable this feature" not "To avoid disabling this feature" 46 47 #### Clarity Guidelines 48 - **One Concept per Sentence**: Keep sentences focused and clear 49 - **Parallel Structure**: Use consistent grammatical patterns in lists 50 - **Specific Language**: "Set timeout to 30 seconds" not "Set a reasonable timeout" 51 - **Avoid Jargon**: Define technical terms or link to definitions 52 53 #### Inclusive Language 54 - **Gender Neutral**: Use "they/them" or rephrase to avoid gendered pronouns 55 - **Accessible Examples**: Use diverse names and scenarios in examples 56 - **Plain Language**: Avoid unnecessarily complex vocabulary 57 - **Cultural Sensitivity**: Avoid idioms and cultural references that may not translate 58 59 ### Technical Writing Principles 60 61 #### Structure and Organization 62 - **Logical Flow**: Information builds from simple to complex 63 - **Scannable Format**: Use headings, lists, and white space effectively 64 - **Consistent Patterns**: Similar content follows similar organization 65 - **Clear Hierarchy**: Heading levels reflect information importance 66 67 #### Code and Examples 68 - **Working Code**: All examples must execute successfully 69 - **Complete Context**: Include necessary imports and setup 70 - **Realistic Examples**: Use practical, real-world scenarios 71 - **Error Handling**: Show proper error handling patterns 72 - **Comments**: Explain non-obvious code sections 73 74 #### Links and References 75 - **Descriptive Link Text**: "See the configuration guide" not "click here" 76 - **Contextual Links**: Link to relevant information when concepts are introduced 77 - **Current Links**: Regularly validate and update all links 78 - **Appropriate Scope**: Link to the most specific relevant section 79 80 ## Template Specifications 81 82 ### Frontmatter Standards 83 84 All documentation files must include YAML frontmatter with these fields: 85 86 ```yaml 87 --- 88 title: "Page Title" # Required: Clear, descriptive title 89 description: "Brief page description" # Required: 1-2 sentence summary for search/navigation 90 category: "getting-started" # Required: One of the five main categories 91 difficulty: "beginner" # Optional: beginner|intermediate|advanced 92 prerequisites: ["installation"] # Optional: Array of prerequisite topics 93 related_topics: ["strategy-dev"] # Optional: Array of related topics 94 last_updated: "2024-01-15" # Optional: Date of last significant update (YYYY-MM-DD) 95 estimated_time: "15 minutes" # Optional: Expected completion time for tutorials 96 tags: ["backtesting", "strategies"] # Optional: Array of searchable tags 97 --- 98 ``` 99 100 #### Field Specifications 101 102 **title**: 103 - Use title case 104 - Be specific and descriptive 105 - Avoid redundant words like "Guide" or "Tutorial" (category indicates this) 106 - Maximum 60 characters for SEO 107 108 **description**: 109 - 1-2 sentences maximum 110 - Explain what the user will learn or accomplish 111 - Use active voice and present tense 112 - Include key terms for searchability 113 114 **category**: 115 - Must be one of: `getting-started`, `guides`, `advanced`, `reference`, `troubleshooting` 116 - Determines navigation placement and user expectations 117 118 **difficulty**: 119 - `beginner`: No prior Planar knowledge required 120 - `intermediate`: Basic Planar concepts understood 121 - `advanced`: Significant Planar experience assumed 122 123 **prerequisites**: 124 - List specific topics/pages user should understand first 125 - Use the same naming as the actual file/section names 126 - Keep list minimal - only true prerequisites 127 128 **estimated_time**: 129 - Realistic estimate for average user 130 - Include time for reading, coding, and testing 131 - Use format: "X minutes" or "X hours" 132 133 ### Tutorial Template 134 135 Use for step-by-step learning content in `getting-started/` and `guides/`: 136 137 ```markdown 138 --- 139 title: "Tutorial Title" 140 description: "What the user will learn and accomplish" 141 category: "getting-started" 142 difficulty: "beginner" 143 prerequisites: ["installation", "basic-concepts"] 144 estimated_time: "20 minutes" 145 --- 146 147 # Tutorial Title 148 149 Brief introduction (2-3 sentences) explaining: 150 - What this tutorial covers 151 - Why it's useful or important 152 - What the user will accomplish 153 154 ## Prerequisites 155 156 Before starting this tutorial, make sure you have: 157 - [Specific requirement with link if needed] 158 - [Another requirement] 159 - [Basic knowledge requirement] 160 161 ## What You'll Learn 162 163 By the end of this tutorial, you will be able to: 164 - [Specific, measurable learning objective] 165 - [Another objective] 166 - [Final objective] 167 168 ## Overview 169 170 [Optional: Brief overview of the process or concept being taught] 171 172 ## Step 1: [Descriptive Action Title] 173 174 [Clear explanation of what this step accomplishes] 175 176 ### Instructions 177 178 1. [Specific action with exact commands/code] 179 2. [Next action] 180 3. [Final action for this step] 181 182 ### Code Example 183 184 185 ### Expected Output 186 187 ``` 188 [Show what the user should see] 189 ``` 190 191 ### Troubleshooting 192 193 If you encounter [specific issue]: 194 - [Specific solution] 195 - [Alternative approach] 196 197 ## Step 2: [Next Action Title] 198 199 [Continue with same pattern] 200 201 ## Verification 202 203 To confirm everything is working correctly: 204 205 1. [Specific test or check] 206 2. [Another verification step] 207 208 You should see [expected result]. If not, [troubleshooting guidance]. 209 210 ## Next Steps 211 212 Now that you've completed this tutorial, you can: 213 - [Logical next tutorial or concept] 214 - [Alternative path] 215 - [Advanced topic to explore] 216 217 ### Recommended Reading 218 - [Link to related guide]: [Brief description] 219 - [Link to reference]: [Brief description] 220 221 ## Troubleshooting 222 223 ### Common Issues 224 225 **Issue**: [Specific problem description] 226 **Solution**: [Step-by-step resolution] 227 228 **Issue**: [Another common problem] 229 **Solution**: [Resolution steps] 230 231 ### Getting Help 232 233 If you're still having trouble: 234 - [Link to relevant troubleshooting section] 235 - [Community support channels] 236 - [How to report bugs] 237 ``` 238 239 ### Reference Template 240 241 Use for API documentation and technical references in `reference/`: 242 243 ```markdown 244 --- 245 title: "Function/Class/Concept Name" 246 description: "Brief description of functionality and purpose" 247 category: "reference" 248 tags: ["api", "relevant-topic"] 249 --- 250 251 # Function/Class/Concept Name 252 253 Brief description (1-2 sentences) of what this is and its primary purpose. 254 255 ## Syntax 256 257 258 ## Parameters 259 260 ### Required Parameters 261 - **`required_param`** (`Type`): Description of what this parameter does and any constraints 262 - **`another_param`** (`Type`): Description with examples of valid values 263 264 ### Optional Parameters 265 - **`optional_param`** (`Type`, default: `default_value`): Description of optional behavior 266 267 ## Returns 268 269 **Type**: `ReturnType` 270 271 Description of what the function returns, including: 272 - Structure of return value 273 - Possible return states 274 - Error conditions 275 276 ## Description 277 278 [Detailed explanation of functionality, behavior, and use cases] 279 280 ### Key Concepts 281 - **Concept 1**: Definition and relevance 282 - **Concept 2**: Definition and relevance 283 284 ## Examples 285 286 ### Basic Usage 287 288 289 ### Advanced Usage 290 291 292 ### Integration Example 293 294 295 ## Error Handling 296 297 ### Common Errors 298 299 **`ErrorType`**: Description of when this occurs 300 301 **`AnotherErrorType`**: Description and resolution 302 303 ## Performance Considerations 304 305 [If applicable, include performance notes, memory usage, or optimization tips] 306 307 ## Related Functions 308 309 - [`related_function`](link): Brief description of relationship 310 - [`another_function`](link): How it complements this function 311 - [`alternative_function`](link): When to use instead 312 313 ## See Also 314 315 ### Tutorials 316 - [Tutorial Name](link): Learn to use this in practice 317 - [Another Tutorial](link): Related workflow 318 319 ### Guides 320 - [Concept Guide](link): Deeper explanation of underlying concepts 321 - [Best Practices](link): Recommended usage patterns 322 323 ### Reference 324 - [Related API](link): Connected functionality 325 - [Configuration Options](link): Relevant settings 326 ``` 327 328 ### Guide Template 329 330 Use for comprehensive explanations in `guides/` and `advanced/`: 331 332 ```markdown 333 --- 334 title: "Guide Title" 335 description: "What this guide covers and who should read it" 336 category: "guides" 337 difficulty: "intermediate" 338 prerequisites: ["basic-concepts", "installation"] 339 estimated_time: "45 minutes" 340 --- 341 342 # Guide Title 343 344 Introduction paragraph explaining: 345 - What this guide covers 346 - Who should read it 347 - What problems it solves 348 - How it fits into the larger Planar ecosystem 349 350 ## Overview 351 352 High-level explanation of the concept, workflow, or feature being covered. 353 354 ### Key Benefits 355 - [Primary advantage] 356 - [Secondary advantage] 357 - [Additional benefit] 358 359 ### When to Use This 360 - [Specific use case] 361 - [Another scenario] 362 - [Problem this solves] 363 364 ## Core Concepts 365 366 ### Concept 1: [Name] 367 **Definition**: [Clear, concise definition] 368 369 **Purpose**: [Why this concept matters] 370 371 **Example**: [Simple illustration] 372 373 ### Concept 2: [Name] 374 [Same pattern as above] 375 376 ## Implementation 377 378 ### Basic Setup 379 380 [Step-by-step instructions for basic implementation] 381 382 383 ### Configuration Options 384 385 #### Required Settings 386 - **`setting_name`**: Description and valid values 387 - **`another_setting`**: Purpose and examples 388 389 #### Optional Settings 390 - **`optional_setting`**: When to use and default behavior 391 - **`advanced_setting`**: Advanced use cases 392 393 ### Advanced Configuration 394 395 [More complex setup for advanced users] 396 397 398 ## Common Patterns 399 400 ### Pattern 1: [Descriptive Name] 401 402 **Use Case**: [When to apply this pattern] 403 404 **Implementation**: 405 406 **Benefits**: [Why this approach is recommended] 407 408 ### Pattern 2: [Another Pattern] 409 [Same structure as above] 410 411 ## Best Practices 412 413 ### Performance 414 - [Specific performance recommendation] 415 - [Another optimization tip] 416 - [Resource management advice] 417 418 ### Security 419 - [Security consideration] 420 - [Safe usage pattern] 421 - [What to avoid] 422 423 ### Maintainability 424 - [Code organization advice] 425 - [Documentation recommendations] 426 - [Testing suggestions] 427 428 ## Integration with Other Features 429 430 ### Feature Integration 1 431 [How this works with other Planar features] 432 433 434 ### Feature Integration 2 435 [Another integration scenario] 436 437 ## Troubleshooting 438 439 ### Common Issues 440 441 #### Issue: [Specific Problem] 442 **Symptoms**: [How to recognize this issue] 443 **Cause**: [Why this happens] 444 **Solution**: [Step-by-step resolution] 445 446 #### Issue: [Another Problem] 447 [Same structure as above] 448 449 ### Debugging Tips 450 - [Diagnostic approach] 451 - [Useful debugging commands] 452 - [Log analysis guidance] 453 454 ## Real-World Examples 455 456 ### Example 1: [Practical Scenario] 457 [Complete, realistic example with context] 458 459 460 **Explanation**: [Why this approach was chosen] 461 462 ### Example 2: [Different Scenario] 463 [Another complete example] 464 465 ## Migration and Upgrades 466 467 [If applicable, guidance for updating from previous versions or migrating from other approaches] 468 469 ## Performance and Scaling 470 471 [If applicable, guidance on performance optimization and scaling considerations] 472 473 ## See Also 474 475 ### Next Steps 476 - [Logical next guide]: [What to learn next] 477 - [Advanced topic]: [For deeper exploration] 478 479 ### Related Guides 480 - [Complementary guide]: [How it relates] 481 - [Alternative approach]: [When to use instead] 482 483 ### Reference Documentation 484 - [API reference]: [Relevant functions] 485 - [Configuration reference]: [Related settings] 486 ``` 487 488 ### Troubleshooting Template 489 490 Use for problem-solving content in `troubleshooting/`: 491 492 ```markdown 493 --- 494 title: "Problem Category or Specific Issue" 495 description: "Brief description of problems covered" 496 category: "troubleshooting" 497 tags: ["error-type", "component"] 498 --- 499 500 # Problem Category or Specific Issue 501 502 Brief description of the problem area and what this page covers. 503 504 ## Quick Diagnosis 505 506 ### Symptoms Checklist 507 - [ ] [Specific symptom to check] 508 - [ ] [Another observable symptom] 509 - [ ] [Error message or behavior] 510 511 ### Immediate Actions 512 If you're experiencing [critical issue]: 513 1. [Immediate step to prevent damage] 514 2. [Quick temporary fix] 515 3. [When to seek additional help] 516 517 ## Common Problems 518 519 ### Problem 1: [Specific Issue Name] 520 521 **Symptoms**: 522 - [Observable behavior] 523 - [Error messages] 524 - [Performance indicators] 525 526 **Likely Causes**: 527 - [Most common cause] 528 - [Alternative cause] 529 - [Less common but possible cause] 530 531 **Solution**: 532 1. [First diagnostic step] 533 2. [Corrective action] 534 3. [Verification step] 535 536 **Prevention**: 537 - [How to avoid this in the future] 538 - [Best practices to follow] 539 540 ### Problem 2: [Another Issue] 541 [Same structure as above] 542 543 ## Diagnostic Procedures 544 545 ### Step-by-Step Diagnosis 546 547 1. **Check [First Thing]** 548 Expected output: [What to look for] 549 550 2. **Verify [Second Thing]** 551 ```bash 552 # System check command 553 ``` 554 If this shows [problem indicator]: [what it means] 555 556 3. **Test [Third Thing]** 557 [Diagnostic procedure] 558 559 ### Advanced Diagnostics 560 561 For complex issues: 562 563 564 ## Error Reference 565 566 ### Error Code: [Specific Error] 567 **Message**: `[Exact error text]` 568 **Meaning**: [What this error indicates] 569 **Resolution**: [How to fix it] 570 571 ### Error Code: [Another Error] 572 [Same structure] 573 574 ## Platform-Specific Issues 575 576 ### Linux 577 [Linux-specific problems and solutions] 578 579 ### macOS 580 [macOS-specific problems and solutions] 581 582 ### Windows 583 [Windows-specific problems and solutions] 584 585 ## Getting Help 586 587 ### Before Asking for Help 588 1. [Information to gather] 589 2. [Steps to try first] 590 3. [How to reproduce the issue] 591 592 ### Where to Get Help 593 - **GitHub Issues**: [When to use and how] 594 - **Community Forums**: [For what types of questions] 595 - **Discord/Chat**: [Real-time help scenarios] 596 597 ### Information to Include 598 When reporting issues, include: 599 - [System information needed] 600 - [Configuration details] 601 - [Error messages and logs] 602 - [Steps to reproduce] 603 604 ## Prevention 605 606 ### Best Practices 607 - [Preventive measure 1] 608 - [Preventive measure 2] 609 - [Monitoring recommendation] 610 611 ### Regular Maintenance 612 - [Maintenance task 1] 613 - [Maintenance task 2] 614 - [Update procedures] 615 ``` 616 617 ## Quality Assurance Standards 618 619 ### Content Review Checklist 620 621 #### Technical Accuracy 622 - [ ] All code examples execute successfully 623 - [ ] API information matches current version 624 - [ ] Links are functional and current 625 - [ ] Prerequisites are accurate and complete 626 - [ ] Instructions produce expected results 627 628 #### Clarity and Usability 629 - [ ] Language is clear and appropriate for audience 630 - [ ] Steps are in logical order 631 - [ ] Examples are realistic and practical 632 - [ ] Success criteria are clearly defined 633 - [ ] Troubleshooting covers common issues 634 635 #### Consistency and Standards 636 - [ ] Follows appropriate template 637 - [ ] Frontmatter is complete and correct 638 - [ ] Formatting follows style guidelines 639 - [ ] Cross-references are appropriate 640 - [ ] Terminology is consistent 641 642 #### User Experience 643 - [ ] Content serves intended user journey 644 - [ ] Difficulty progression is appropriate 645 - [ ] Navigation aids are helpful 646 - [ ] Integration with existing content is smooth 647 648 ### Automated Validation 649 650 All content is automatically checked for: 651 - **Link Health**: Internal and external link validation 652 - **Code Execution**: All Julia examples must run successfully 653 - **Template Compliance**: Proper structure and frontmatter 654 - **Style Consistency**: Markdown formatting and conventions 655 656 ### Manual Review Process 657 658 1. **Technical Review**: Subject matter expert validates accuracy 659 2. **Editorial Review**: Writing quality and clarity assessment 660 3. **User Experience Review**: Usability and journey effectiveness 661 4. **Final Approval**: Maintainer approval for publication 662 663 ## Maintenance Procedures 664 665 ### Regular Updates 666 - **Monthly**: Review getting-started content for accuracy 667 - **Quarterly**: Update code examples for new releases 668 - **Annually**: Comprehensive content audit and refresh 669 670 ### Version Control 671 - All changes tracked in Git with descriptive commit messages 672 - Major updates documented in changelog 673 - Breaking changes communicated to users 674 675 ### Community Contributions 676 - Clear contribution guidelines and templates 677 - Responsive review process 678 - Recognition and credit for contributors 679 - Mentorship for new contributors 680 681 This document is itself subject to these standards and should be updated as our practices evolve.