|
| 1 | +# Radius Blog Contribution Guidelines |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +The Radius project blog serves as a vital communication channel between the Radius community and the broader cloud-native community. This guide establishes standards for creating content that is both technically accurate and accessible to developers worldwide. |
| 6 | + |
| 7 | +All blog contributions must be relevant to Radius and the broader cloud-native ecosystem. Content should provide genuine value to readers through actionable insights, practical examples, or meaningful technical depth. |
| 8 | + |
| 9 | +## Content Types |
| 10 | + |
| 11 | +1. **Feature announcements** introduce new capabilities with context about problems solved and practical applications in real-world workflows. |
| 12 | + |
| 13 | +2. **Community stories** showcase how organizations use Radius to solve specific problems, focusing on implementation details and measurable outcomes. These highlight small, focused use cases. |
| 14 | + |
| 15 | +3. **Release announcements** balance comprehensive coverage with readability, highlighting significant changes and providing clear upgrade paths. Breaking changes require detailed migration steps. |
| 16 | + |
| 17 | +4. **Integration guides** demonstrate real scenarios with Radius and other cloud-native technologies, including configuration examples and troubleshooting guidance. |
| 18 | + |
| 19 | +5. **Case studies** provide detailed analysis of production deployments, examining usage patterns, implementation challenges, and solutions developed. |
| 20 | + |
| 21 | +## Target Audience |
| 22 | + |
| 23 | +1. **Platform engineers and Developers** need architectural guidance, best practices, and integration patterns for internal developer platforms. |
| 24 | + |
| 25 | +2. **Enterprise decision makers** require strategic insights, implementation considerations, and evidence of successful deployments at scale. |
| 26 | + |
| 27 | +3. **Open source contributors** seek detailed technical explanations, architecture discussions, and contribution guidance. |
| 28 | + |
| 29 | +## Content Requirements |
| 30 | + |
| 31 | +- Length of the blog post should be between 800-1000 words |
| 32 | +- Every statement must be verifiable through documentation, code examples, or reproducible demonstrations |
| 33 | +- Include complete, working code that readers can adapt and use successfully |
| 34 | +- Provide actionable insights that readers can apply immediately |
| 35 | +- Focus on demonstrable facts and measurable outcomes, avoiding promotional language |
| 36 | +- Ensure all external references point to authoritative, up-to-date sources |
| 37 | + |
| 38 | +## Location and structure of post content |
| 39 | + |
| 40 | +Create a new markdown file for each blog post in the appropriate year directory under `radblog/content/posts`. The file name should be the title of the blog post, with hyphens in place of spaces. For example, the file name for a blog post titled "Hello world" would be `hello-world.md`. |
| 41 | + |
| 42 | +The content of the blog post markdown file should be in the following format: |
| 43 | + |
| 44 | +```md |
| 45 | +--- |
| 46 | +date: "YYYY-MM-DDT07:00:00-07:00" |
| 47 | +title: "Blog post title" |
| 48 | +linkTitle: "Shorter blog post title in links pane" |
| 49 | +author: "[Firstname Lastname](<link_to_linkedin_or_github>)" |
| 50 | +type: blog |
| 51 | +--- |
| 52 | + |
| 53 | +Blog post content here. |
| 54 | +``` |
| 55 | + |
| 56 | +## Article Structure |
| 57 | + |
| 58 | +- **Title**: Clear and descriptive, working well in search results and social media |
| 59 | +- **Introduction**: Establish context and explain the problem being addressed |
| 60 | +- **Main content**: Logical progression with descriptive headings and practical examples |
| 61 | +- **Conclusion**: Summarize key takeaways and provide clear next steps |
| 62 | +- **Learn More**: Link to official documentation and authoritative sources |
| 63 | + |
| 64 | +## Writing Guidelines |
| 65 | + |
| 66 | +### Style and Tone |
| 67 | +- **Conversational and friendly**: Make technical topics accessible without being frivolous |
| 68 | +- **User-focused**: Write in second person ("you") rather than first person ("we") |
| 69 | +- **Clear and concise**: Use simple, direct language accessible globally |
| 70 | +- **Active voice**: Make content more direct and engaging |
| 71 | +- **Present tense**: Use when describing current features and capabilities |
| 72 | +- **Objective**: Avoid promotional language, superlatives, and unsupported claims |
| 73 | + |
| 74 | +### Language Standards |
| 75 | +- **Global accessibility**: Avoid idioms, cultural references, and region-specific examples |
| 76 | +- **American English spelling**: Use standard conventions consistently |
| 77 | +- **Terminology consistency**: Use established Radius terminology throughout |
| 78 | +- **Inclusive language**: Follow cloud-native community standards |
| 79 | +- **Technical accuracy**: All statements must be verifiable and current |
| 80 | +- **Descriptive links**: Use meaningful text describing destination content |
| 81 | +- **Conditional clarity**: Put conditions before instructions |
| 82 | + |
| 83 | +### Content Quality Standards |
| 84 | +- **Evidence-based**: Support all claims with documentation, code, or examples |
| 85 | +- **Practical focus**: Include working code examples and step-by-step instructions |
| 86 | +- **No pre-announcements**: Avoid announcing unavailable future features |
| 87 | +- **Avoid speculation**: Don't make undocumented assumptions about user needs |
| 88 | +- **No redundancy**: Each section should provide unique value |
| 89 | +- **Technical depth**: Provide sufficient detail for understanding and implementation |
| 90 | +- **User-centric**: Focus on what users can accomplish |
| 91 | + |
| 92 | +## Formatting Standards |
| 93 | + |
| 94 | +### Typography |
| 95 | +- **Proper nouns**: Capitalize Radius entities including: Applications, Environments, Recipes, Resource Types, Containers, Secrets, Routes, Gateways, Resource Groups |
| 96 | +- **Headings**: Use sentence case (first word and proper nouns only) |
| 97 | +- **File names**: Use kebab-case (`radius-release-guide.md`) |
| 98 | +- **UI elements**: Use **bold** for buttons, menus, and dialog boxes |
| 99 | +- **Code elements**: Use `monospace` for function names, variables, and file paths |
| 100 | +- **Serial commas**: Use consistently in lists of three or more items |
| 101 | + |
| 102 | +### Code and Technical Content |
| 103 | +- **Code blocks**: Use fenced blocks with language specification for syntax highlighting |
| 104 | + |
| 105 | + ```bash |
| 106 | + # Example bash code block |
| 107 | + ``` |
| 108 | +- **Commands**: Separate multiple commands into individual blocks |
| 109 | +- **Output**: Show expected output in separate blocks |
| 110 | +- **File paths**: Use backticks for file names and paths |
| 111 | +- **Placeholders**: Use descriptive names and enclose them in angle brackets (`<YOUR-APPLICATION-NAME>` not `app1`) |
| 112 | + |
| 113 | +### Visual Content |
| 114 | +- **Images**: Use high-resolution or vector images with Hugo shortcode `img` |
| 115 | + |
| 116 | + ``` |
| 117 | + {{< image src="images/<your_image_name>" alt="Screenshot of image x" width="500" >}} |
| 118 | + ``` |
| 119 | +- **Alt text**: Provide descriptive text explaining what images show |
| 120 | +- **Consistency**: Maintain consistent visual styling within posts |
| 121 | +
|
| 122 | +### Links and References |
| 123 | +- **Descriptive text**: Use specific descriptions instead of "click here" |
| 124 | +- **Internal links**: Connect to relevant Radius documentation and blog posts |
| 125 | +- **External links**: Point to authoritative, current sources |
| 126 | +- **GitHub references**: Include links to issues, PRs, and commits when relevant |
| 127 | +
|
| 128 | +## Submission Process |
| 129 | +
|
| 130 | +### Before Submitting |
| 131 | +1. **Self-review**: Check technical accuracy, style adherence, and target audience clarity |
| 132 | +2. **Technical review**: Have domain experts verify accuracy and completeness |
| 133 | +3. **Editorial review**: Ensure clarity, grammar, and style consistency |
| 134 | +
|
| 135 | +### Pull Request Requirements |
| 136 | +- **Branch naming**: Use descriptive names (`blog/radius-app-graph`) |
| 137 | +- **Commit messages**: Follow conventional commit format |
| 138 | +- **Description**: Explain post topic, target audience, and key points |
| 139 | +- **Staging site**: A staging site will automatically get created and linked to PR to review and test |
0 commit comments