Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/
Join our discussions of documentation issues here on the blog and on Slack.
Don’t use images of text, examples, code snippets, or other media solely comprised of text.
Include screenshots with a full window; include the window’s title bar in the screenshot.
Maintain consistency of the operating system (OS) in screenshots – don’t use a Linux OS in one and macOS in the other.
Don’t include personally identifying information (PII) in screenshots and other images.
If there is PII in a screenshot, redact it with a solid color with 100% opacity. Don’t use blurs, pixelation, mosaic effects, or similar image-processing effects to redact PII, as these effects can be reversed to reveal the original information.
If you’re exporting an image to a format that can include information on separate layers (for example, PDF or TIFF), flatten the image on export.
Use drawing tools to create diagrams.
For diagrams (such as network flows, system architectures) use vector graphic formats like SVG. SVG files stay sharp when you zoom in on the image. If you don’t have an SVG image, use a PNG image as it provides better image quality than other raster image formats.
Don’t use image maps as they prove to be difficult for accessibility. Image maps are also problematic for a responsive design implementation that adapts to different viewport sizes, while also being complex. Instead, write a list of text references following the image.
In most cases, introduce an image with an introductory sentence that initiates the image that follows. If the heading of the content explains what the image is about, and no additional context is required, then don’t include an introductory statement. You can introduce a image with an imperative statement.
The introductory sentence can end with a colon or a period. Use a period if the introductory content is extended, and a colon if the introductory statement is shorter and immediately precedes the image. The text preceding the colon must distinctly stand alone as a complete sentence. That is, don’t introduce a image with a partial statement.
There are different types of text associated with images. Alt text is a concise description of the image that can replace the image in situations when the image isn’t visible as well as accessible documentation. For example, people using screen readers, people using text-only browsers or people having a low-bandwidth internet connection can benefit from alt text. Alt text should consider the context of the image, not just its content. For more information, see alt attribute.
An image caption is a short description of the image. An image description is a textual explanation of the image which can be used to convey detailed descriptions than image captions. Figure captions are optional. When using the <figcaption> element, both the <figcaption> and <img> elements must be wrapped in the <figure> element to ensure that the figure caption is properly associated with the image.
Tip:Recommended (HTMLHTMLHTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites.):
alt="The WordPress mascot Wapuu."
<figcaption><b>Image 1.</b> Image of WordPress mascot Wapuu.</figcaption>
<p>The official WordPress mascot - the adorable cartoon creature Wapuu, was first revealed in 2011.
Use an alt attribute to provide an alternative text for an image; the value must be an appropriate replacement for the image. Alt text is used to write accessible documentation and is used in assistive technologies such as screen readers, text-only browsers or low-bandwidth internet connections. The alt attribute helps support navigability in screen readers, markup validation, and search engine optimization (SEO). If the image is decorative (not informative) or it’s provided only as a visual aid for information that is already expressed in text, then provide empty alternative text (alt="") so it will be ignored by assistive technologies.
The alt attribute is required when using the <img> element, even if it is an empty string (alt=""). If you don’t use the alt attribute, screen readers might read the filename instead.
As per the HTML specification, “the most general rule to consider when writing alternative text is the following: the intent is that replacing every image with the text of its alt attribute not change the meaning of the page.” So if the alternative text is redundant with surrounding text or it’s not useful to visually impaired readers, use the empty tag.
When writing alt text, follow these guidelines:
Write full sentences.
Use punctuation in alt text. When encountered with punctuation, screen readers pause before continuing.
Don’t replace alt text with image captions.
Don’t include phrases such as Image of or Photo of.
Write consistent alt text for repeated occurrences of images.
Avoid using all-caps in alt text. Some screen readers read capital letters as each letter individually.
When writing alt text, consider the context of the image in addition to the content of the image.
Whenever possible keep alt text length to 155 characters or less for better search engine optimization. If you exceed the 155 character limit, include a brief summary of the image in the alt attribute and also include the longdesc attribute to link to a more extensive description of the image. The longdesc attribute value should be a link, not text.
Captions are brief, concise summaries of an image or a figure.
When writing image captions, follow these guidelines:
Use the form, “Figure NUMBER.DESCRIPTION“.
Use punctuation in image captions.
In general, avoid using directional language such as the image above, top, below, left-hand side, lower-right side in instructions to locate images or other figures. Directional language proves to be difficult for accessibility or for localization.
Don’t include the image caption in a sentence referencing the image.
A description provides a more detailed, textual explanation of information depicted by an image. Any new information should be conveyed through text, and not introduced through a figure or image.
The image description should not be confused with the longdesc attribute, which can be used to provide a more lengthy description of the content and context of an image than can be conveyed in the alt attribute’s recommended 155 character limit.
When writing image descriptions, follow these guidelines:
Write image descriptions when captions are inadequate in conveying complete information.
In most cases, avoid embedding text containing information in images, figures, or screenshots. Particularly, when a new concept is being introduced to the reader, try not to include it in figures. Text in images impedes accessibility and increases localization costs if they are localized. If you must embed text in an image, then ensure the same information is also provided in a form that people with visual disabilities can use, such as an image description.
When you must include text in figures and images, use the following guidelines:
Write concise text. Avoid complete sentences and punctuation when possible.