Differences

This shows you the differences between two versions of the page.

--- evergreen-docs:dig_style_guide [2020/10/27 10:52] – [Common Mistakes] aneiman
+++ evergreen-docs:dig_style_guide [2024/11/27 22:11] (current) – [Language] lhernandez
@@ Line 9: / Line 9: @@
 ==== Add a Table of Contents to the top of each AsciiDoc file ====
-This simply means adding this AsciiDoc line near the top of each ''.adoc'' file. (The old system added this during the HTML build process.)
+This simply means adding this AsciiDoc line near the top of each ''.adoc'' file. The toc designation should go on the 2nd line of your file, just below the top header. (The old system added this during the HTML build process.)
-<code asciidoc>:toc:</code>
-==== Use underline style headings instead of prefix/suffix style ====
+<code asciidoc>= Heading =
+:toc:</code>
+==== Use prefix/suffix style headings instead of underline style ====
 The basic reasons are:
@@ Line 52: / Line 56: @@
 For historical purposes, the old xref syntax is below
-**DO NOT USE THIS!** The below is an example of the now-deprecated cross reference style:
+The below is an example of the now-deprecated cross reference style. **DO NOT USE THIS!**
 <code asciidoc>
 <<reporter_creating_folders,Creating Folders>>
@@ Line 63: / Line 67: @@
 ===== General =====
   * **Avoid changing section titles**. These are used to auto-generate anchor tags which are often used for links. Change with care, and check for links in other docs.
-  * Always **review changes** before committing to master (and check the updated web page the next day to make sure it worked right).
+  * Always **review changes** before committing to main (and check the updated web page the next day to make sure it worked right).
-  * Always use **spell-check** on new content (including when porting old docs into master).
+  * Always use **spell-check** on new content (including when porting old docs into main).
   * AsciiDoc code lines should be 80 characters long or shorter. (Occasionally, exceptions are necessary for correct syntax.)
   * Screenshots should be smaller than 1050 pixels wide (when possible).
+  * Rather than recreating documentation text in multiple adoc files, instead link directly to the main adoc for the feature.
 ===== Formatting =====
 ==== Headers ====
@@ Line 103: / Line 108: @@
     * This allows AsciiDoc to auto-number the items as needed.
   * **Ampersands** should be left as is (&). Don't use an HTML entity (which ironically causes errors in our HTML generator).
+    * If an ampersand appears in the staff client or OPAC use the ampersand in the documentation.  In all other cases use the word 'and' instead of an ampersand.
   * Any **code and command line commands** should be marked as +code+ or `code`
     * If the code or command is hard to read when included in the paragraph, consider using a code block:
@@ Line 181: / Line 187: @@
   * **Don't add a border or shadow** to the screenshot image. That can be done globally to all screenshots in the docs via CSS, if we want it.
   * **When replacing a screenshot**, if the intention of the image isn't changing, then create a new image with the same file name as the old image.  However, if you are essentially removing a screenshot and adding a different one (with a different focus or purpose), it is better to use a different file name (and update the reference to it in the docs!), and probably to change the related text in the documentation also.
+  * Image syntax: ''image::images/ascii_doc_name/imagename.png[alt text]''. Example for an image in the Cloning Shared Templates documentation: ''image::images/reporter_cloning_shared_templates/clone-report-template-3.png[Clone Selected Template]''.
+  * Starting with version 3.8 screenshots should be put into folders with the same name as the page the images appear on.  For example, if your page is circulation_policies.adoc in the admin folder the image folder would be called circulation_policies and would be in admin -> assets -> images -> circulation_policies.
+  * Alt text: Please remember to include alt text in the image syntax for descriptive and accessibility reasons.
+  * Screen shots can be from any installation of Evergreen, as long as it does not contain any personal identifiable information, and is based on stock Evergreen.
 ===== Common Mistakes =====
@@ Line 211: / Line 220: @@
   * Consider incorporating ideas from [[documentation:style_guide|The Book of Evergreen: Style Guide]]
+=====Creating Accessible Evergreen Documentation=====
+This introduction to writing accessible documents for Evergreen covers the basics. This guide is not exhaustive. Use the resources available at the end of this document to continue learning more. Remember, accessibility is an ongoing process. As you continue to learn, take time to bring the new information into your regular work and workflows!
+The document has four sections: a quick action summary, more details on accessibility, a checklist for reviewing docs, and resources.
+====Quick Actions for Accessible Documentation====
+  * Keep your writing simple and direct.
+  * Use consistent language and terms across sections and pages.
+  * Use bullet points and section header formats to create smaller chunks of content.
+  * Use descriptive text when creating links, instead of phrases like ‘click here’.
+  * Add alternative text to your images.
+  * Put important information first.
+====More Details on Accessibility====
+===Plain Language===
+Make sure that your content is clear and understandable for a wide range of people. Use plain language when writing to make it easier for people to understand your message. Plain language helps people with disabilities, novices, and people who are not fluent. Avoid using technical words or phrases that need shared cultural knowledge or inside jokes. If you do use complex words, provide more context or definitions.
+===Consistent Names===
+Write your instructions using the names and words users will see in the interface you are describing. When possible, make sure that the words match section to section. See the [[evergreen-docs:dig_style_guide#wording|Wording and Standard Terminology]] sections for preferred terminology.
+===Break Your Content into Small Groups===
+Break your content into smaller pieces when you need to share a lot of information. Use bulleted lists and small labeled sections. This helps people focus on the most important pieces of information. Label the sections using headings to make the document easier to navigate. See the [[evergreen-docs:dig_style_guide#headers|Headers]] section for how to format sections headings
+Each page should have a single level one heading. Additional headings should be nested in a logical order and not skip levels. A good guideline when considering headings is to treat them like a document outline.
+  * Heading Level 1
+    * Heading Level 2
+      * Heading level 3
+        * Heading level 4
+      * Heading Level 3
+    * Heading Level 2
+    * Heading Level 2
+      * Heading Level 3
+===Link Formatting===
+Use descriptive text to make it easier for folks to understand where the URL will take them. Do not use “click here” or “read more” as the text for links. In the example, “See Viewing Report Output for more information,” the words “viewing report output” should be the linked text.
+===Screenshots===
+Include images and screenshots to aid with understanding. Avoid excessive use of images. Too many images can be distracting when people are trying to follow a set of instructions.
+===Alternative Text===
+Alternative text, also called alt text, is a brief text description of an image. Alt text provides a text alternative for people with disabilities using screen readers. Alt text can also help people with a low bandwidth internet connection.
+Alt text descriptions should be brief. There is no standard length for alt text. Typical length suggestions are 125 - 250 characters. The description should include the information you are expecting sighted people to gain from the image. Ask yourself:
+  * Why is this image here?
+  * What is the important feature of this image?
+  * Have I described this image in the text already?
+In the example below, the contents of the screen were partially described in the document text. This means that the alt text should focus on the information a sighted user would get from the image, such as the fact that part of the screen has been highlighted.
+> In the left pane under My Folders a subfolder has been highlighted. In the other pane, the check mark next to a template has been selected.
+If the image is part of a larger set with repeated content across multiple steps, then begin your alt text with a note that this is part of a set. Then describe what is unique about this image. This allows you to focus on the essential information instead of repeating information already noted in the first item in the series. For example, > Image 3 of 5 showing Edit Prediction Pattern. MFHD Indicators tab has been selected. The Compression Display Options field is set to can compress or expand. The Caption Evaluation is set as captions verified all levels present.
+Including information on the set of images also allows screen reader users to skip a known number of images if they do not need the information in those instructions.
+====Review Checklist====
+This checklist is intended to help you spot signs of common accessibility problems. Answering No to these question may be a sign of an accessibility issue.
+  * Does the information go from most important information to least specific?
+  * Have you used plain language where possible?
+  * Have you defined any technical terms or acronyms the first time they are used?
+  * Have you broken your content into smaller chunks or lists?
+  * Does the page have a single title or Heading 1 area, and does it make sense for the page?
+  * Can the text be understood without the need for insider jokes or knowledge?
+  * Has alt text been considered for all images and icons?
+  * Does the alt text have the same information you would expect sighted users to gain from the image?
+====Resources To Learn More====
+===Language===
+  * [[https://www.w3.org/WAI/WCAG2/supplemental/#cognitiveaccessibilityguidance|WAI WCAG2 Cognitive Accessibility Guidance]]
+  * [[https://www.plainlanguage.gov/|Plain Language Action and Information Network (PLAIN)]]
+  * [[https://blog.pope.tech/2018/07/26/why-ambiguous-links-are-problematic/|“Click Here” to “Read More”: Why Ambiguous Links are Problematic]]
+  * [[https://www.plainlanguage.gov/resources/checklists/web-checklist/|Checklist for Plain Language on the Web]]
+===Images===
+  * [[https://www.w3.org/WAI/tutorials/images/decision-tree/|An alt decision tree]]
+  * [[https://www.sitelint.com/blog/best-practices-for-writing-good-alt-text/|Best practices for writing good alt text]]
+  * [[https://www.perkins.org/resource/how-write-alt-text-and-image-descriptions-visually-impaired/|How to Write Alt Text and Image Descriptions for the visually impaired ]]