Skip to content

Commit fbe4f1d

Browse files
authored
Recommend that Explainers use Markdown or similar. (#21)
Copied from w3ctag/tag.w3.org#61.
1 parent 450c150 commit fbe4f1d

File tree

1 file changed

+10
-1
lines changed

1 file changed

+10
-1
lines changed

index.bs

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Markup Shorthands: markdown yes, css no
1212
Assume Explicit For: yes
1313
Boilerplate: conformance no
1414
Required IDs: introduction, good-explainers, tips, end-user-need, write-simply
15-
Required IDs: describe-proposal, alt-text, alternatives, history, template
15+
Required IDs: describe-proposal, alt-text, alternatives, history, deep-linking, template
1616
Abstract: An explainer introduces a problem that a group of people are trying to solve,
1717
and helps everyone with an interest in the target problem find consensus on a good way to solve it.
1818
@@ -143,6 +143,15 @@ Link to all prior art in either
143143
your [considered alternatives](https://github.com/w3ctag/tag.w3.org/blob/main/explainers/template.md#considered-alternatives) section
144144
or your [references and acknowledgements](https://github.com/w3ctag/tag.w3.org/blob/main/explainers/template.md#references--acknowledgements).
145145

146+
## Enable Easy Deep Linking ## {#deep-linking}
147+
148+
You should host your explainer as HTML at a stable, readable URL,
149+
ideally next to where the specification is expected to land.
150+
Use a format
151+
that makes it easy for reviewers to link directly to sections inside the document,
152+
like Markdown or HTML.
153+
It's fine to use a host like GitHub that automatically renders Markdown.
154+
146155
----
147156

148157
By following these guidelines, you can create clear, concise, and accessible explainers that effectively communicate your proposed web standards specifications for W3C TAG review.

0 commit comments

Comments
 (0)