diff --git a/guidelines/formatting.txt b/guidelines/formatting.txt index 9bef1dd..ff0cf14 100644 --- a/guidelines/formatting.txt +++ b/guidelines/formatting.txt @@ -243,6 +243,8 @@ Notes and guidelines: * Make sure you use a URL suitable for video embedding. +* This line must start at the left margin of your text file. + * See <> for guidelines on embedding videos. diff --git a/guidelines/guidelines-writing.txt b/guidelines/guidelines-writing.txt index a2bbbdf..862f5f3 100644 --- a/guidelines/guidelines-writing.txt +++ b/guidelines/guidelines-writing.txt @@ -138,6 +138,9 @@ additional information can be added: Prerequisite knowledge:: Add links in this section to other topics within the same book that cover knowledge someone would need to understand before reading this topic. +Site prerequisites (task topics):: + Most site prerequisites listed here should include link(s) to the topic(s) + that explain how to create the necessary content, configure the site, etc. Expand your understanding (task topics):: Add links in this section to task topics in the same book that would help solidify or broaden the knowledge covered in this topic. @@ -162,6 +165,21 @@ guidelines: promotion or advertising. * The page or video must be freely available, without paying, logging in, or subscribing to the site. +* If a video is embedded (instead of just linked) in the guide, it must also be + captioned; ideally, linked videos should also be captioned. (Captioning makes + a video accessible, according the + https://www.w3.org/2008/06/video-notes[W3C Accessibility Guidelines]). +* Embedded videos must also be translatable. For example, the video producer + could provide an English transcript, caption files, and video source files, + and the video could be released under a license that would allow someone to + release a new video with the sound and captions replaced by translations. Or, + the caption file could be provided for translators, and the video producer + could commit to adding foreign-language subtitles to the original video as the + captions are translated into other languages. In either case, instructions for + downloading source materials and translating should be provided when the video + is embedded into the text, by adding the information to a README-VIDEOS.txt + file in the source directory. + *Attributions* diff --git a/guidelines/templates.txt b/guidelines/templates.txt index 071e494..2746581 100644 --- a/guidelines/templates.txt +++ b/guidelines/templates.txt @@ -111,10 +111,19 @@ If you have a multiple-paragraph step, separate the paragraphs by + signs. Notes: * If your task involves filling out a form, include a screen shot. -* Also include a table of fields and values to fill in. +* Also include a table of fields and values to fill in. See example below. * The last step should be something that shows them the task has been completed. Include a screen shot. +Sample table of fields and values: + +[width="100%",frame="topbot",options="header"] +|================================ +|Field name |Explanation |Example value +|Menu link title |Title to be displayed in the menu |Opening hours +|Second field |Second explanation |Second example value +|================================ + ==== Expand your understanding // In this section, you can make cross-references to other task topics in this @@ -145,6 +154,10 @@ Remove this placeholder text. // In this section, embed videos that exactly cover this topic. For videos // that are related but do not exactly cover the topic, add links in the // Additional resources section instead. +// +// Syntax to embed a video (remove the // to make it not a comment, and make +// sure the word "video" starts at the left margin of your text file): +// video::https://www.youtube.com/embed/HymQsDOcT3E[title="Name of video"] Remove this placeholder text. @@ -256,6 +269,10 @@ Remove this placeholder text. // In this section, embed videos that exactly cover this topic. For videos // that are related but do not exactly cover the topic, add links in the // Additional resources section instead. +// +// Syntax to embed a video (remove the // to make it not a comment, and make +// sure the word "video" starts at the left margin of your text file): +// video::https://www.youtube.com/embed/HymQsDOcT3E[title="Name of video"] Remove this placeholder text. diff --git a/templates/concept-topic.txt b/templates/concept-topic.txt index ea41060..634e9ae 100644 --- a/templates/concept-topic.txt +++ b/templates/concept-topic.txt @@ -78,6 +78,10 @@ Remove this placeholder text. // In this section, embed videos that exactly cover this topic. For videos // that are related but do not exactly cover the topic, add links in the // Additional resources section instead. +// +// Syntax to embed a video (remove the // to make it not a comment, and make +// sure the word "video" starts at the left margin of your text file): +// video::https://www.youtube.com/embed/HymQsDOcT3E[title="Name of video"] Remove this placeholder text. diff --git a/templates/task-topic.txt b/templates/task-topic.txt index 2c1ac87..ae77c6e 100644 --- a/templates/task-topic.txt +++ b/templates/task-topic.txt @@ -90,10 +90,19 @@ If you have a multiple-paragraph step, separate the paragraphs by + signs. Notes: * If your task involves filling out a form, include a screen shot. -* Also include a table of fields and values to fill in. +* Also include a table of fields and values to fill in. See example below. * The last step should be something that shows them the task has been completed. Include a screen shot. +Sample table of fields and values: + +[width="100%",frame="topbot",options="header"] +|================================ +|Field name |Explanation |Example value +|Menu link title |Title to be displayed in the menu |Opening hours +|Second field |Second explanation |Second example value +|================================ + ==== Expand your understanding // In this section, you can make cross-references to other task topics in this @@ -124,6 +133,10 @@ Remove this placeholder text. // In this section, embed videos that exactly cover this topic. For videos // that are related but do not exactly cover the topic, add links in the // Additional resources section instead. +// +// Syntax to embed a video (remove the // to make it not a comment, and make +// sure the word "video" starts at the left margin of your text file): +// video::https://www.youtube.com/embed/HymQsDOcT3E[title="Name of video"] Remove this placeholder text.