Article Writing Rules

#

Before writing any article, read this file in full. Do not scan the entire content tree. Only read the input Marko provides and apply the rules below.

The produced draft will be polished by the technology-blog-writer agent. Focus on correctness and completeness — the agent handles voice, vocabulary, and style cleanup.

How to use Marko’s input

#

Marko provides a raw markdown file with:

• H2 headings (##) to declare sections
• Code blocks without fences — raw Go code
• 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 expands the bullet points into full paragraphs. Each bullet point should become 2–4 sentences minimum — explain the point, give context for why it matters, and connect it to the surrounding code or concept. Do not list bullet points verbatim. Do not compress multiple bullet points into a single sentence.
3. Wrap each raw code block with the correct markdown fence: ```go ... ```
4. Add a short descriptive label above each code block on its own line (e.g., **Client initialisation**, **Main loop**).
5. Write ## Conclusion (3–5 sentences, no padding) and ## Useful Resources (2–5 links, never invented).

Never invent technical claims or code examples Marko has not provided. Never add sections Marko has not declared with an H2.

Project-specific conventions

#

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

Links

• Link to other articles on this blog on first mention: [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”

Useful Resources section

• 2–5 links, bulleted
• Always includes relevant references: official Go docs, relevant packages, GitHub repos, referenced external resources
• Format: - [Link text](url "Link text")
• Never invent URLs

Article 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.

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 we covered…”
• The conclusion may end with a forward-looking sentence about the next article in the series

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.