Content Creation Hub

Practical guidance for writing, editing, and publishing high-quality technical content. This hub focuses on developer-facing articles, tutorials, and reference material: clear structure, accurate code examples, reproducible steps, and SEO that helps readers find and apply the knowledge.

🚀 Getting Started

New to technical writing for CalmOps? Start here:

• Read the editorial standards in the About hub — tone, frontmatter, and structure expectations.
• Follow the short checklist: clear title, 150–160 char description, required frontmatter, code examples that run, and external authoritative resources.
• Draft the article locally using the content/<category>/ structure and validate with hugo --quiet before publishing.

Recommended quick-start articles:

• Complete Guide to Note-Taking & Outlining — craft the article outline before writing.
• Hugo Content Workflow — how to write, preview, and publish with Hugo.
• SEO for Technical Articles — best practices for titles, descriptions, headings, and internal links.

📚 Main Categories

✍️ Writing & Structure (Drafting → Final)

How to plan and write developer-friendly content.

• Titles & frontmatter: create searchable, descriptive metadata.
• Introductions: state what the reader will learn and why it matters.
• Headings: logical H2→H3 structure, descriptive headings.
• Code examples: runnable, realistic, and include expected output.
• Troubleshooting & FAQs: add for longer tutorials.

🧭 Outlines & Learning Paths

Design sequences of articles and “what to learn next”.

• Mapping prerequisites, steps, and expected outcomes.
• Creating progressive learning paths that follow CalmOps templates.

🔍 SEO & Discoverability

Write for humans and search engines.

• SEO-friendly descriptions (150–160 chars), keywords, and tags.
• Internal linking strategy: link to related CalmOps articles.
• Structured data: include JSON-LD where templates allow.

🧹 Editing & Quality Assurance

Peer review and technical accuracy.

• Fact-check code examples and commands.
• Run examples locally (docker, virtualenv, language-specific REPLs).
• Use linters and markdown validators.

🖼️ Media & Diagrams

Visuals that clarify architecture and flow.

• Use SVG/PNG/WebP images in static/images/<category>/.
• Prefer code-driven diagrams (Mermaid) for architecture sketches.
• Optimize images for web: AVIF/WebP and responsive sizes.

⚙️ Publishing & CI

Hugo build, pagefind, deploy, and indexation.

• Local preview: hugo server --noHTTPCache -w -D --bind "0.0.0.0".
• Run SEO validation scripts and Pagefind indexing before deploy.
• Use the repository’s deploy scripts: ./deploy-calmops.sh --fast.

🎯 Learning Paths

Path 1: From Outline to Published Article (1–2 days)

1. Create a focused outline with headings and code snippets.
2. Draft content in plain markdown, add frontmatter.
3. Verify code examples locally and add expected output text.
4. Add images/diagrams, captions, and alt text.
5. Run hugo locally, fix warnings, and publish with deploy-calmops.sh --fast.
   Outcome: A published CalmOps article following editorial standards.

Path 2: SEO-First Technical Guide (2–4 days)

1. Keyword research and 150–160 char description.
2. Draft with clear problem → solution flow and concise examples.
3. Add schema (HowTo/Article) in templates if applicable.
4. Internal-link to 3 complementary CalmOps articles.
5. Post-publish: measure traffic and iterate (update lastmod).
   Outcome: Improved organic discoverability and engagement.

Path 3: Long-Form Tutorial (4–7 days)

1. Expand outline into numbered step-by-step sections with prerequisites.
2. Provide complete working examples and expected outputs for each major step.
3. Add troubleshooting, common errors, and alternatives.
4. Peer review and test by a second engineer.
5. Publish and collect feedback for clarifications.
   Outcome: Comprehensive tutorial that users can follow end-to-end.

📊 Key Statistics (example targets)

• Article frontmatter: 150–160 char description required.
• Minimum article length: 250 lines for Tutorials / Deep Dives (follow CalmOps content rules).
• Code examples: include error handling and expected output.
• Tags: 2–5 relevant tags per article.
• Internal links: at least 3 links to existing CalmOps content for SEO and reader flow.

🔗 Quick Reference

Title & frontmatter checklist:

• title: clear, includes primary keyword.
• description: 150–160 chars, answers “what will I learn?”
• date/lastmod: set to today when publishing.
• draft: false for published articles.
• tags: 2–5, use existing tags when possible.
• keywords: 3–6 relevant search terms.
• aiAttribution: include aiGenerated/aiAssisted fields when applicable.

Publishing checklist:

• Run hugo locally and fix build warnings.
• Run Pagefind indexing and SEO scripts.
• Confirm public/ output looks correct on a test server.
• Deploy using ./deploy-calmops.sh --fast or as required.

Image & media best practices:

• Store images in static/images/<category>/ using kebab-case.
• Provide alt text for accessibility.
• Optimize formats: prefer AVIF/WebP and provide fallbacks.

📚 Browse All Articles

🎓 Who This Hub Is For

• Technical writers and engineers producing CalmOps content.
• Maintainers who review, edit, and publish articles.
• Contributors transforming rough drafts into production-ready articles.
• Editors ensuring articles meet CalmOps quality and SEO standards.

📖 External Resources

• Hugo documentation — https://gohugo.io/documentation/
• Google Search Central (SEO basics) — https://developers.google.com/search/docs/overview
• MDN Writing Docs (technical authoring guidance) — https://developer.mozilla.org/
• “The Elements of Style” / Plain-language guides for clarity and concision.
• “Write the Docs” community — https://www.writethedocs.org/ for docs processes and checklists.

If you’d like, I can:

• Generate a PR-ready diff for this file and a short commit message, or
• Expand “Browse All Articles” into a full alphabetical index with 1-line summaries for every entry, or
• Produce a templated article checklist file to include with every new article (example: scripts/article-checklist.md).