/blog-writing

name: blog-writing
description: Use when writing, drafting, or publishing a blog article for metraton.github.io

Blog Writing

Jorge's blog (metraton.github.io) is where he thinks out loud about agentic systems, context engineering, and the intersection of architecture and AI. The articles are bilingual (English and Spanish), grounded in real experience, and written in first person. They are not corporate content -- they are reflections from someone building these systems daily.

The Writing Process

1. Find the story first

Every article starts with something that actually happened -- a deployment that went sideways, a late-night refactor, a conversation that shifted your thinking. The story is the anchor. Without it, you are writing a tutorial, not an article.

Ask Jorge: "What happened recently that surprised you or changed how you think about something?" The best topics come from moments where the outcome was different from the expectation.

2. Build the brief

Before writing a single paragraph, define: title, audience, core thesis (one sentence), and format. Jorge's natural format is **Strategic Insight** -- personal experience analyzed through a technical lens, ending with a transferable lesson.

The audience is engineers, solution architects, AI practitioners, and tech leaders. They do not need hand-holding but they appreciate honesty about what did not work.

3. Draft in Markdown, iterate with Jorge

Write the first draft in Markdown at `/home/jorge/ws/me/<slug>.md`. Work section by section -- do not dump an entire draft and ask "what do you think?" Each section should be reviewed before moving to the next.

**Article structure** (not rigid, but this is Jorge's natural flow):

• Opening story -- what happened, told personally
• The problem -- what was broken or surprising
• Investigation -- what you looked into and found
• The shift -- the insight or reframe
• In practice -- what changed, concretely
• Results -- evidence it worked
• Closing thought -- punchy, memorable, one line

4. Principles that matter

**Examples must be real.** Not "imagine a team that..." but "I was deploying to Cloud Run when..." If you cannot point to something that actually happened, the example does not belong.

**Each section adds something new.** Do not repeat the same example or insight across sections. If the investigation section already showed the problem, the "in practice" section should show the solution -- not restate the problem.

**Quotes add weight when grounded.** Citing Anthropic, Hinton, or other thought leaders works when the quote connects directly to the experience. A quote floating without context is decoration.

**Technical terms stay in English in both languages.** LLM, skills, agent, Cloud Run, Terraform -- these do not get translated.

**Closing lines are signatures.** "Built with context.", "Built with reasoning." -- short, confident, tied to the article's thesis.

5. Convert to bilingual HTML

Once the Markdown draft is approved, convert to the bilingual HTML format. The Spanish version is not a mechanical translation -- it is natural Latin American Spanish, with the same voice and directness. Read `reference.md` for the HTML template and front matter structure.

Final HTML goes in: `/home/jorge/ws/me/metraton.github.io/_posts/YYYY-MM-DD-slug.html`

6. Editorial review

Before publishing, pass through both language versions checking:

• Spelling, grammar, flow, and consistency
• HTML entities are correct (`&mdash;` `&rsquo;` `&eacute;` etc.)
• Technical terms stay in English in the Spanish version
• Gender consistency for borrowed terms ("los skills" not "las skills")
• No broken anglicisms ("marcar" not "flagear")
• Citations link to real, accessible URLs

7. Visual verification

Ensure Jekyll is running locally (see `reference.md` for environment details). Preview at localhost:4000. Use Playwright to take screenshots at desktop (1280x900) and mobile (375x812). Check that all visual components render, no horizontal overflow, responsive breakpoints work.

8. Publish

Commit and push to `master` in the blog repo. GitHub Pages deploys automatically.

9. Live verification

Wait ~45s after push for GitHub Pages to build. Use Playwright to screenshot the live URL and compare against the localhost preview.

10. LinkedIn post

Draft a sharing post: 1-3 sentence personal hook connecting to the article's insight, the link, and a bilingual P.D. See `reference.md` for the template. Conversational but technical tone, no aggressive hashtags -- the article preview image does the heavy lifting.

Jorge's Voice

• First person, always. "I was deploying..." not "The team deployed..."
• Honest about failures and iterations -- does not pretend things worked the first time
• Confident but not preachy. States what he found, not what everyone should do
• Direct. Short sentences when making a point. Longer when telling a story
• Latin American perspective -- references to the region's tech community are natural, not forced

Anti-Patterns

• Writing generic content that could appear on any corporate blog
• Translating English to Spanish mechanically instead of rewriting naturally
• Dumping an entire draft without iterating section by section
• Using hypothetical examples when real ones exist
• Repeating the same insight across multiple sections