blog-content-guide from Intranet

Author: lyind

content/docs/content/blog-content-guide/_index.md

@@ -1,206 +1,185 @@
 ---
 title: Blog content guide
-description: "An overview of how to approach blog content at Giant Swarm. "
-classification: confidential
+linkTitle: Blog content guide
+weight: 20
+description: A comprehensive guide for creating high-quality blog content for
+  Giant Swarm's website.
+classification: public
+expiration_in_days: 365
 ---
-## Core Principles
+# Giant Swarm Blog Content Guide
 
+## Purpose and Vision
 
-Every blog post should:
+The Giant Swarm blog serves as a platform to:
 
+- Demonstrate our deep expertise in platform engineering
+- Share valuable insights that help organizations overcome common challenges
+- Showcase our unique perspective on industry developments
+- Build trust through transparency about our approaches and methodologies
+- Establish thought leadership in the Kubernetes and platform engineering space
 
-- Transform complex challenges into clear, actionable insights
-- Demonstrate deep technical expertise while remaining accessible
-- Connect technical solutions to business value
-- Share authentic experiences that readers can learn from
+## Content Strategy
 
+### Content Categories
 
+#### Technical Content (Primary Focus)
 
+- Platform Engineering Insights
+- Kubernetes Best Practices
+- GitOps Implementation
+- Observability Solutions
+- Security Architecture
+- Cluster Management
+- Developer Tooling
+- Autoscaling Strategies
+- Technical Tutorials
+- Performance Optimization
 
+#### Business & Culture Content
 
-## Types of Impact
+- Industry Trends Analysis
+- Inside Giant Swarm
+- Product Updates & Roadmap
+- Team Insights
+- Case Studies
+- Best Practices
+- Management Perspectives
 
-### Technical Deep Dives
+### Content Types
 
+#### Deep Technical Articles
 
-Show readers exactly how to solve pressing challenges:
+- Detailed technical explanations
+- Step-by-step tutorials
+- Architecture deep-dives
+- Performance analysis
+- Security implementations
 
+#### Thought Leadership
 
-- Start with the problem, not the solution
-- Include real-world scenarios and failure modes
-- Provide complete, tested solutions
-- Share performance implications and trade-offs
-- Include troubleshooting guides for common issues
+- Industry trend analysis
+- Future of platform engineering
+- Technology adoption strategies
+- Best practices compilations
+- Expert opinions
 
+#### Behind-the-Scenes
 
-Example structure:
+- Engineering culture insights
+- Development process details
+- Team perspectives
+- Product development journey
+- Lessons learned
 
+## Content Quality Guidelines
 
-```
-# How We Reduced Kubernetes Deployment Times by 80%The problem: Our customers were struggling with 20+ minute deployment timesThe impact: Release delays, frustrated developers, missed opportunitiesOur journey: The approaches we tried, what failed, what workedThe solution: Detailed implementation with code and architectureThe results: Performance data, developer feedback, lessons learned
-```
+### Technical Accuracy
 
-### Industry Insights
-
-
-Help readers navigate complex decisions:
-
-
-- Start with a current challenge in the field
-- Present multiple approaches with pros/cons
-- Share concrete examples from our experience
-- Provide clear decision frameworks
-- Include cost and complexity trade-offs
-
-
-Example structure:
-
-
-```
-# Platform Engineering: Build vs Buy vs ExtendThe dilemma: What we're seeing across our customer baseThe approaches: Detailed analysis of each optionReal examples: Success and failure storiesDecision framework: How to choose the right approachImplementation guide: First steps for each path
-```
-
-
-
-
-
-### Technical Tutorials
-
-Transform complex topics into learnable skills:
-
-
-- Start with the end goal and prerequisites
-- Break complex processes into clear steps
-- Include debugging and troubleshooting
-- Show common mistakes and how to avoid them
-- Provide verification steps for each stage
-
-
-Example structure:
-
-
-```
-# Implementing Zero-Trust Security in KubernetesThe goal: What you'll achieve and why it mattersPrerequisites: Required setup and knowledgeStep-by-step guide: Detailed implementationVerification: How to test your implementationTroubleshooting: Common issues and solutions
-```
-
-## Writing Excellence
-
-### Technical Precision
-
-- Use precise technical language
-- Show both what to do and what not to do
-- Include performance implications
+- All technical content must be peer-reviewed
+- Include working code examples when applicable
+- Provide clear explanations of complex concepts
 - Link to relevant documentation
-
-### Reader Connection
-
-- Open with a challenge readers are facing
-- Share authentic experiences and lessons
-- Show the journey, including failures
-- Connect technical details to business impact
-- Close with clear next steps
-
-### Visual Communication
-
-- Architecture diagrams that tell a story
-- Performance charts with analysis
-- Decision flow diagrams
-- Comparison tables
-- Warning boxes for gotchas
-- Pro-tip boxes for expert insights
-
-## Content Validation Process
-
-### Initial Assessment
-
-
-Content Goals Alignment
-
-- Educate: Does it provide clear learning value?
-- Convince: Is the argument compelling?
-- Align: Does it match our vision?
-
-
-Core Elements Check
-
-- Tech: Technical accuracy and depth
-- People: Reader perspective and needs
-- Goals: Clear objectives and outcomes
-
-### Validation Questions
-
-- Does this content solve a current problem?
-- Is it relevant to our target audience?
-- How long will this content remain valuable?
-- Is the technical depth appropriate?
-- Can we support all claims and examples?
-- Will this go out of date quickly?
-- Can we make it evergreen?
-
-### Quality Standards
-
-Technical Review
-
-- Code examples must be tested
-- Architecture diagrams must be accurate
-- Performance claims must be verified
-- Security implications must be considered
-- Edge cases must be addressed
-
-Impact Review
-
-- Does it solve a real problem?
-- Is the solution complete?
-- Are trade-offs clearly explained?
-- Is there clear business value?
-- Will readers be able to implement it?
-
-### Publishing Checklist
-
-Summary and TLDR
-
-- Clear main points
-- Key takeaways highlighted
-
-Reader Journey
-
-- Clear path through content
-- Natural progression of ideas
-- Logical flow maintained
-
-Call to Action (CTA)
-
-- Clear next steps
-- Relevant resources
-- Engagement opportunities
-
-## Making Complex Topics Accessible
-
-### Use Progressive Disclosure
-
-1. Start with the big picture
-1. Add necessary context
-1. Dive into technical details
-1. Cover edge cases
-1. Include advanced topics
-
-### Connect to Reader Challenges
-
-- Time pressure → Show quick wins first
-- Quality concerns → Focus on reliability
-- Cost constraints → Include ROI analysis
-- Team dynamics → Share collaboration approaches
-- Technical debt → Show incremental improvement
-
-## Bringing It All Together
-
-Great blog posts combine:
-
-- Deep technical expertise
-- Real-world experience
-- Clear business value
-- Actionable insights
-- Authentic voice
+- Update content when technology changes
+
+### Writing Style
+
+#### Voice and Tone
+
+- Write with authority but without arrogance - we're sharing knowledge, not showing off
+- Use active voice: "We deployed the cluster" vs "The cluster was deployed"
+- Address the reader directly using "you" to create engagement
+- Include your personal experiences and lessons learned - authenticity matters
+- Keep sentences short and purposeful (aim for max 25 words per sentence)
+
+#### Technical Writing
+
+- Define technical terms on first use, even if they seem obvious
+- Use concrete examples instead of abstract concepts
+- Include real-world scenarios that readers can relate to
+- Break down complex ideas into digestible chunks
+- Show both what works AND what doesn't - failed approaches are valuable lessons
+
+#### Engagement Techniques
+
+- Open with a hook that connects to reader pain points
+- Use analogies to explain complex technical concepts
+- Include dialogue and personal experiences where relevant
+- Ask rhetorical questions to make readers think
+- End sections with forward-looking statements or questions
+
+### Structure
+
+#### Title and Headers
+
+- Main title should be specific and searchable
+- Use question-style headers to address reader concerns directly
+- Keep headers under 60 characters
+- Ensure headers follow a logical hierarchy
+- Use action words in headers: "Implementing" vs "Implementation"
+
+#### Content Flow
+
+1. Introduction (10% of total length)
+- Hook with a real problem or challenge
+- State what the reader will learn
+- Establish your credibility on the topic
+1. Main Content (80% of total length)
+- One main idea per section
+- Progressive disclosure - start basic, get complex
+- Include code blocks with explanatory comments
+- Add diagrams for system architecture or workflows
+- Use numbered steps for tutorials
+- Include troubleshooting sections for common issues
+1. Conclusion (10% of total length)
+- Summarize key takeaways
+- Provide next steps or additional resources
+- End with a call to action or thought-provoking question
+
+#### Visual Elements
+
+- Custom diagrams for architecture and workflows
+- Screenshots with annotations
+- Code blocks with syntax highlighting
+- Comparison tables for different approaches
+- Charts for performance data
+- Warning boxes for common pitfalls
+- Info boxes for pro tips and shortcuts
+
+### Value Proposition
+
+Every post should:
+
+- Address specific platform engineering challenges
+- Provide actionable insights or solutions
+- Demonstrate Giant Swarm's expertise
+- Connect with reader pain points
+- Include clear takeaways
+
+## Content Creation Process
+
+### Planning
+
+1. Topic identification based on:
+- Current industry challenges
+- Customer questions and feedback
+- Technical innovations
+- Strategic company initiatives
+- Market trends
+1. Content brief development:
+- Main thesis/argument
+- Key points to cover
+- Target audience
+- Expected outcomes
+- Required technical depth
+
+### Writing
+
+1. Initial draft development
+1. Technical review
+1. Editorial review
+1. Final approval
+1. Publication scheduling