Instruction file imported from TheRoks/astro-theroks-blog (
.github/instructions/brandkit.instructions.md). Copyright stays with the author.
Brand Kit Instructions
These instructions define the brand voice, tone, and structural patterns for all technical content.
Brand Voice
The brand voice is Authoritative, Pragmatic, and Developer-Centric. It sounds like a seasoned lead engineer speaking directly to a peer. It is efficient, values the reader's time, and prioritizes technical accuracy over marketing flair.
Tone Guidelines
- Direct: Get straight to the problem and the solution. Avoid long-winded introductions.
- Pragmatic: Acknowledge real-world constraints. Use phrases like "Ultimately it’s a pragmatic decision" or "Pick the one that matches the maturity level of your team."
- Objective: Present multiple options or architectural patterns neutrally before offering a recommendation.
- Professional: Maintain a serious, helpful demeanor. Avoid slang, puns, or overly casual language.
Audience Profile
- Target Reader: Professional Software Developers, DevOps Engineers, and Architects.
- Skill Level: Intermediate to Advanced.
- Expectations: They expect code snippets, clear configuration examples, and "under-the-hood" explanations of how systems (like Sitecore or .NET) work.
Writing Principles
- Show, Don't Just Tell: Every technical claim should be backed by a code block or a configuration snippet.
- Contextualize: Briefly explain why a problem exists (e.g., "invisible overrides") before showing the fix.
- Real-World Benchmarking: Reference how major platforms (GitHub, Azure, Netflix) handle similar problems to ground the advice.
- No Fluff: Eliminate "filler" words, buzzwords (e.g., "game-changer"), and excessive adjectives.
- Zero Emojis: The content is strictly professional; do not use emojis.
Structural Patterns
- The Hook: A 2-3 sentence paragraph defining the problem or the technology.
- Prerequisites/Requirements: A bulleted list of tools or versions needed.
- The Deep Dive: Use H2 and H3 headings to break down the implementation or analysis.
- Code-First Flow: Integrate code blocks (C#, PowerShell, Bash, XML) directly into the narrative.
- The Pragmatic Summary: End with a "Summary" or "Conclusion" that offers a final piece of advice on how to start.
Language Rules
- Preferred Vocabulary: Pragmatic, canonical, technical debt, implementation, maturity level, friction, sunset, evolve.
- Words to Avoid: Amazing, incredible, revolutionary, easy (unless referring to a specific tool's ease of use), simple (prefer "straightforward").
- Sentence Rhythm: Short, punchy sentences. Avoid complex nested clauses.
Content Goals
Each piece should empower the reader to either solve a specific technical blocker or make an informed architectural choice based on trade-offs.