skills/research-writing/references/technical_article_blog_patterns.md

# Technical Article and Blog Patterns

## Core article

A useful technical article usually needs:
- reader promise;
- problem/context;
- mechanism/explanation;
- evidence/examples;
- trade-offs/failure modes;
- practical takeaway.

Not every article needs all sections.

## Openings

Good patterns:
- concrete problem;
- unexpected result;
- meaningful change;
- practical question;
- short scene grounded in real experience supplied by the user.

Avoid generic technology hype.

## Explanatory sequence

Useful flow:

`problem → mental model → mechanism → example → trade-offs → decision/use`

For "what I learned" articles:

`what I built → what looked simple → what failed/changed → lessons → practical pattern`

Do not invent first-person experiences.

## Technical depth

Match the audience:
- beginner;
- practitioner;
- senior engineer;
- architect/researcher.

Define prerequisites rather than flattening everything to beginner level.

## Code

Use code when it demonstrates a mechanism or improves understanding.

State:
- language/version when material;
- omitted boilerplate;
- production/security caveats.

Avoid unexplained code dumps.

## Tables and figures

Use tables for:
- comparisons;
- mappings;
- decision criteria;
- compact factual reference.

A figure should answer a question:
- request lifecycle;
- architecture boundary;
- benchmark comparison;
- state machine;
- before/after.

## Conclusions

Add value instead of repeating the introduction.

Useful endings:
- decision rule;
- design principle;
- checklist;
- next experiment;
- unresolved uncertainty.

## Personal voice

Use first person only when the user's real experience supports it.

Never invent "I spent weeks debugging..." anecdotes.