Article Writing Rules

#

Before writing any article, read this file in full. Then read a maximum of 2 existing articles from content/article/golang/ for style reference — no more. Do not scan or read the entire content tree. Only read the input file Marko provides and apply the rules below.

How to use Marko’s input

#

Marko provides a raw markdown file with the following structure:

• H2 headings (##) to declare sections
• Code blocks without any markdown formatting — raw Go code, no fences
• Bullet points below each code block explaining what that code demonstrates

Your job:

1. Write a short introduction (no H2 heading) — 2-4 paragraphs setting context. Include inline links to relevant Go standard library packages or official docs when referencing specific features.
2. For each section (H2 heading Marko provided): write prose that responds to the bullet points. The bullet points are the substance — expand them into flowing sentences, do not list them verbatim.
3. Wrap each raw code block with the correct markdown code fence: go ...
4. Add a bold label above each code block: **Label name**
5. Write a conclusion (## Conclusion) based on the most important points Marko made across all bullet points — not a mechanical summary, but the key takeaways a reader should leave with.
6. Provide a ## Useful Resources section with meaningful links — official Go docs, relevant packages, referenced external resources. Never invent URLs.

Never invent technical claims or code examples Marko hasn’t provided. Never add sections Marko hasn’t declared with an H2.

Writing style — extracted from existing articles

#

Language naming

• Always write “Go” when referring to the programming language — never “Golang” or “golang”
• Exception: tag names, package import paths, and URLs where “golang” is technically required

Voice and tone

• First person, direct, experienced practitioner — not a teacher talking down, not a neutral explainer
• Occasionally personal: brief anecdotes from real production experience are welcome and natural (“There was a time when…”, “I have spent years…”, “In my experience…”)
• Honest about trade-offs and imperfect solutions — Marko doesn’t pretend everything is clean
• Confident but not arrogant — states opinions clearly without hedging everything
• Dry wit is fine, but never forced. One clever line per article maximum.

Sentence and paragraph structure

• Short to medium sentences. No compound sentences stacked three deep.
• One idea per paragraph. Paragraphs are 2-4 sentences typically.
• No bullet points inside article body prose — everything is written out as sentences
• Transitions between sections are natural, often a single sentence that bridges the previous section to the next topic

What Marko does NOT do

• No motivational language (“This is exciting!”, “Let’s dive in!”)
• No excessive hedging (“it might be worth considering”, “you could potentially”)
• No padding — if a point is made, move on
• No repetitive summaries mid-article (“As we saw above…”)
• No “In conclusion” as the literal first word of the conclusion section — just write it

How Marko introduces concepts

• Leads with context or personal experience, then the definition/pattern — not the other way around
• Uses a real-world analogy or production scenario before abstract explanation
• When introducing a pattern or concept for the first time, briefly acknowledges where it comes from (Martin Fowler, Eric Evans, Gang of Four) with a link — but does not spend paragraphs on history

Code examples

• Every code block has a bold label above it: **Label name**
• Labels are descriptive: “Simple Repository example”, “The Right Approach”, “A Wrong Approach”, “Order Aggregate”
• Code is always Go unless the article explicitly covers another language
• Comments inside code blocks are minimal — // some code, // some fields, // handle error are acceptable placeholders
• Output is shown inline as comments: // Output: // true
• Wrong approaches are shown before right approaches — Marko teaches by contrast
• Never alter the logic of code Marko provides. Format only.

Links

• Link to other articles on the blog when referencing related patterns: [Repository](/article/golang/practical-ddd-repository "Repository")
• Link to external references inline on first mention: [Martin Fowler](https://martinfowler.com/ "Martin Fowler")
• Link text is the concept name, never “click here” or “this article”

Article structure

#

Front matter — fill in per project CLAUDE.md conventions. Ask Marko for date if not provided.

Opening paragraph (no heading)

• 2-4 paragraphs, no H2 heading above them
• Sets context: why this topic matters, Marko’s personal relationship with it, what the article covers
• Does NOT start with “In this article we will…” — that’s banned
• Does NOT start with a definition — starts with context or experience

Sections (H2 headings)

• Each section covers one concept or one variation
• Heading is a noun or short phrase, not a question: “Stateless”, “The Anti-Corruption Layer”, “Partial mocking of Interface”
• Sections flow from foundational to advanced
• Each section: brief intro sentence → code example(s) with labels → prose explanation of what the code shows and why it matters

Conclusion (H2 heading: “## Conclusion”)

• 1 short paragraph, 3-5 sentences
• Summarises what was covered without repeating every point
• Often ends with a forward-looking sentence (what to apply this to, what comes next in the series)
• Never starts with “In conclusion”

Useful Resources (H2 heading: “## Useful Resources”)

• Bulleted list of 2-5 links
• Always includes relevant references: Martin Fowler, Go Dev docs, official package docs, GitHub repos
• Format: - [Link text](url "Link text")

Series handling

#

If the article is part of a series, add series and series_order to front matter. Reference previous articles naturally in the opening: “In the previous article I covered…”

Length

#

• DDD/architecture articles: 1500-2500 words
• Tutorial/standard library articles: 1000-2000 words
• Do not pad to hit a word count. Stop when the content is complete.

What to do if Marko’s bullet points are ambiguous

#

Make a reasonable interpretation based on the code examples provided. Flag the ambiguity at the end of the draft with a note: “NOTE FOR MARKO: [specific question]” — do not silently guess on technical matters.