readable-content

Name: readable-content
Author: Owl-Listener

82stars25forks

How to install readable-content?

owl-listener/inclusive-design-skills/readable-content

$npx -y skills add Owl-Listener/inclusive-design-skills --skill readable-content

Installs into the current project.

Summary

Write and structure content for diverse reading abilities and cognitive styles. Use when writing long-form content, help documentation, product descriptions, policies, terms, or any content that needs to be understood by a wide audience. Triggers on: readability, reading level, t

Files · 1

View on GitHub

SKILL.md

1	# Readable Content Design
2
3	Structure and write content so that people with different reading
4	abilities, attention spans, and cognitive styles can find what they
5	need and understand it.
6
7	## Core Principle
8
9	People don't read — they scan. Design your content for the scan first,
10	the read second.
11
12	## Content Structure
13
14	### Inverted Pyramid
15	Put the most important information first. Assume the reader might
16	stop at any point.
17	- Paragraph 1: the key message or answer
18	- Paragraph 2: the essential supporting detail
19	- Paragraph 3+: background, context, nuance
20
21	### Chunking
22	- One topic per section
23	- One idea per paragraph
24	- Maximum 3–4 sentences per paragraph
25	- Maximum 5–7 paragraphs per section before a new heading
26	- Break walls of text with headings every 2–3 paragraphs
27
28	### Scannable Elements
29	- Descriptive headings that summarise the section content
30	- Bold key terms (sparingly — if everything is bold, nothing is)
31	- Bulleted lists for 3+ related items (maximum 7 items per list)
32	- Tables for comparative information
33	- Pull-out boxes or callouts for critical information
34
35	## Writing for Readability
36
37	### Sentence Level
38	- Aim for 15–20 words per sentence
39	- One idea per sentence
40	- Active voice: "We'll send your order" not "Your order will be sent"
41	- Concrete language: "in 3 working days" not "shortly"
42	- Address the reader directly: "You can..." not "Users may..."
43
44	### Word Level
45	- Use the simplest word that carries the meaning
46	- Define specialist terms on first use
47	- Spell out acronyms on first use: "Web Content Accessibility
48	Guidelines (WCAG)"
49	- Avoid idioms, metaphors, and culturally specific references
50	- Avoid double negatives: "You can continue" not "You cannot
51	not proceed"
52
53	### Paragraph Level
54	- First sentence carries the key point (front-loading)
55	- Supporting sentences elaborate or provide evidence
56	- No paragraph should require reading the previous one to make sense
57	- Transition words help flow: "However," "For example," "This means"
58
59	## Content Types With Specific Needs
60
61	### Instructions and How-To
62	- Numbered steps for sequential tasks
63	- One action per step
64	- Start each step with a verb: "Click", "Enter", "Select"
65	- Include what the user should see after each step
66
67	### Policies, Terms, and Legal Content
68	- Plain language summary at the top
69	- Full text below for those who need it
70	- Define all legal terms in context
71	- Use examples to illustrate abstract concepts
72
73	### Error and Warning Content
74	- What happened (specific)
75	- What it means for the user
76	- What to do next (single clear action)
77	- Grade 4–6 reading level always
78
79	### Data and Numbers
80	- Round numbers where precision isn't needed (about 2 million, not
81	1,987,453)
82	- Provide context: "40% — nearly half"
83	- Use charts with text summaries for complex data
84	- Don't assume numeracy — explain what the numbers mean
85
86	## Assessment Questions
87
88	1. Is the most important information first?
89	2. Can someone scanning only headings and bold text get the key message?
90	3. Are sentences under 20 words on average?
91	4. Is every paragraph under 4 sentences?
92	5. Would someone with a grade 8 reading level understand this?

People who liked this also viewed

6 picks

Type

readable-content

82stars25forks

View on GitHub

How to install readable-content?

owl-listener/inclusive-design-skills/readable-content

$npx -y skills add Owl-Listener/inclusive-design-skills --skill readable-content

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Readable Content Design
2
3	Structure and write content so that people with different reading
4	abilities, attention spans, and cognitive styles can find what they
5	need and understand it.
6
7	## Core Principle
8
9	People don't read — they scan. Design your content for the scan first,
10	the read second.
11
12	## Content Structure
13
14	### Inverted Pyramid
15	Put the most important information first. Assume the reader might
16	stop at any point.
17	- Paragraph 1: the key message or answer
18	- Paragraph 2: the essential supporting detail
19	- Paragraph 3+: background, context, nuance
20
21	### Chunking
22	- One topic per section
23	- One idea per paragraph
24	- Maximum 3–4 sentences per paragraph
25	- Maximum 5–7 paragraphs per section before a new heading
26	- Break walls of text with headings every 2–3 paragraphs
27
28	### Scannable Elements
29	- Descriptive headings that summarise the section content
30	- Bold key terms (sparingly — if everything is bold, nothing is)
31	- Bulleted lists for 3+ related items (maximum 7 items per list)
32	- Tables for comparative information
33	- Pull-out boxes or callouts for critical information
34
35	## Writing for Readability
36
37	### Sentence Level
38	- Aim for 15–20 words per sentence
39	- One idea per sentence
40	- Active voice: "We'll send your order" not "Your order will be sent"
41	- Concrete language: "in 3 working days" not "shortly"
42	- Address the reader directly: "You can..." not "Users may..."
43
44	### Word Level
45	- Use the simplest word that carries the meaning
46	- Define specialist terms on first use
47	- Spell out acronyms on first use: "Web Content Accessibility
48	Guidelines (WCAG)"
49	- Avoid idioms, metaphors, and culturally specific references
50	- Avoid double negatives: "You can continue" not "You cannot
51	not proceed"
52
53	### Paragraph Level
54	- First sentence carries the key point (front-loading)
55	- Supporting sentences elaborate or provide evidence
56	- No paragraph should require reading the previous one to make sense
57	- Transition words help flow: "However," "For example," "This means"
58
59	## Content Types With Specific Needs
60
61	### Instructions and How-To
62	- Numbered steps for sequential tasks
63	- One action per step
64	- Start each step with a verb: "Click", "Enter", "Select"
65	- Include what the user should see after each step
66
67	### Policies, Terms, and Legal Content
68	- Plain language summary at the top
69	- Full text below for those who need it
70	- Define all legal terms in context
71	- Use examples to illustrate abstract concepts
72
73	### Error and Warning Content
74	- What happened (specific)
75	- What it means for the user
76	- What to do next (single clear action)
77	- Grade 4–6 reading level always
78
79	### Data and Numbers
80	- Round numbers where precision isn't needed (about 2 million, not
81	1,987,453)
82	- Provide context: "40% — nearly half"
83	- Use charts with text summaries for complex data
84	- Don't assume numeracy — explain what the numbers mean
85
86	## Assessment Questions
87
88	1. Is the most important information first?
89	2. Can someone scanning only headings and bold text get the key message?
90	3. Are sentences under 20 words on average?
91	4. Is every paragraph under 4 sentences?
92	5. Would someone with a grade 8 reading level understand this?

People who liked this also viewed

6 picks

Type