34 lines
1.9 KiB
Markdown
34 lines
1.9 KiB
Markdown
Review written sections of a learning guide on the topic "{topic}" (format: {format_name}) for readability.
|
|
Audience: beginners.
|
|
|
|
SECTION SPECIFICATION (target state):
|
|
{spec}
|
|
|
|
SECTIONS:
|
|
{sections}
|
|
|
|
Review each section:
|
|
1. Does the section teach the concept understandably for a beginner with no prior knowledge — does it frame it, explain the how/why, make an example concrete? Not so dense that only someone who already knows the topic can follow it.
|
|
2. Readability (note genuine flaws):
|
|
- Sentences over ~20 words (never over 25), or nested sentences with several interjections.
|
|
- An enumeration (steps/options/requirements) written as one long prose sentence that should be a Markdown list.
|
|
- Wall of text: one dense block without paragraphs that could be split into several.
|
|
- More than ~4 new technical terms left unexplained at first occurrence.
|
|
3. Conciseness (superfluous material harms learning — note genuine flaws):
|
|
- Repetition: the same statement multiple times, just reworded.
|
|
- Trivia spelled out at length, filler sentences, preambles, meta-comments with no new content.
|
|
- An example that contributes nothing to understanding.
|
|
→ note as "too long/redundant — shorten without loss of information". IMPORTANT: shortening never means dropping a subblock — each one stays.
|
|
4. Are the examples short, simple, plausibly correct — and in the topic-appropriate format per the specification (no code block around prose examples, no prose pseudo-example where code is required)?
|
|
5. Is the Markdown clean (no broken code blocks, no placeholders, no foreign text)?
|
|
|
|
You only REVIEW and note problems — you change nothing. Note only genuine flaws, no matters of taste.
|
|
|
|
Write ONLY the JSON file to: {out_path}
|
|
|
|
Format — all in order:
|
|
{{"ok": true}}
|
|
Otherwise (section title EXACTLY as above):
|
|
{{"problems": [{{"section": "exact section title", "problem": "…"}}]}}
|
|
{extra}
|