Creating Accessible Knowledge Articles in Salesforce

Video Transcript

Hello, and welcome to Creating Accessible Knowledge Articles in Salesforce. My name is Tracy Axelson, and I will be facilitating this course.

First, let's go over our training agenda. We'll be covering clean HTML with the WYSIWYG editor. Text formatting options. Proper heading usage. Numbered and bulleted lists. Links and smart links. Accessible images. Accessible video embedding. Making tables accessible. And additional components to avoid.

Clean HTML with the WYSIWYG editor. Copy and paste without formatting. Websites use overarching styles to make all pages feel cohesive. The University branding is built into our style sheet. And our fonts and font sizes are already tested and approved for accessibility. Copying and pasting from other applications will import the styles from those applications as inline styles. Inline styles override the style sheets.

Do not use WYSIWYG font options. Font selector, font size selector, font color, and background color should all be avoided. Also, strikethrough, superscript, and subscript, screen readers read these as normal text. So users will miss the meaning intended.

Text formatting options. Use bold to emphasize text, but use it sparingly. Bold text is a purely visual indicator of importance or emphasis. Screen readers do not indicate the text is bold. If you truly need to emphasize content, consider if your bolded text should be a heading.

Do not use italics, as it's more difficult to read visually and can cause issues for the neurodivergent community. Do not apply underlining to text. Underlined text on the web indicates hyperlinks. So using underline will create confusion when there is no hyperlink associated with the text.

Use left alignment only. Centering, justifying text, or right-aligning text should be avoided. Left-aligned text is easiest to read for most users, especially users with visual tracking issues or dyslexia.

Use standard capitalization. Do not use all caps unless using all caps for an acronym. All caps is generally harder to read and can come across as aggressive to the reader. In addition, depending on the words that are in the caps, a screen reader may read the word as an acronym rather than the word that you intended.

We have a new knowledge article. The title is Installing Slack. As I scroll down, you can see the Article Body field. And in that is the new WYSIWYG editor. All of the buttons are not visible initially. If you click this little More indicator, you get to see all of the possible buttons that are available.

Let's just do some pasting first. If I go over to my document, where I've been working on my knowledge article text, I can copy this text. And in my article, if I hit Control-V or Apple-V, I get a dialog box that asks if I'd like to remove the formatting or keep the formatting. Definitely want to remove the formatting. As we discussed, any formatting that you bring over from another application, that will overwrite the style sheets with inline styles. So we definitely don't want to do that.

So I have added this text. But it's a little bit hard to see everything when I'm scrolling. I have to scroll up and down. So I'm going to use the Fullscreen button to open this up in a larger screen view. This is great.

Now, as I mentioned before, you can use bold. You probably want to do that very sparingly. But we definitely don't want to use bold for large swaths of text. It's really just a visual indicator. And it does not get communicated to your screen readers.

Your alignment buttons are here. But as I said before, you should really only use Align left. We don't use the font selector. We don't use the font size selector. This is the default. And it's not actually being applied to this text. If I hit the Source Code view, you can see that there's no fonts applied.

OK, let's discuss proper heading usage. Never use a heading level based on how much you like the style or look. Headings must be nested properly. Heading 1 is reserved for the page title. Heading 2 should be used for the main sections of your article. Headings 3, 4, 5, and 6 should be used only for sections nested below the heading size before it.

Do not apply styling, such as bold, to headings, as they have their own styles already. Headings should be unique and should describe the content in that section. Do not apply headings to list items.

Back in my knowledge article, I'd like to take a look at the heading structure. When I brought my knowledge article over from Word, it included an upper-level heading. I don't need this heading. The heading for the article comes from the title field in the knowledge article itself. So I don't need to include one in the article content.

However, looking at this document, I have two sections that are very, very similar. And the first section has "Mac Version" highlighted. And the second section has "Windows Version" highlighted. I think, instead of highlighting this text, I can unbold that in both of them and instead include a heading.

So I'm going to click before "Step 1" in the top section and write "Installing Slack for Mac." And I'm going to change this to a heading style. Note-- heading 1 is available, but we can't use it. That's the page title. So heading 2 would be the next level.

Now I'm going to go down here and do the same thing for the Windows section. "Installing Slack for Windows." Selecting it, I can then choose Headings, Heading 2. So now I have two heading 2's on my page. And then the content below each one of them is the content for that section.

Let's talk about numbered and bulleted lists. Lists are easily scanned. And they provide additional information to visitors who are using adaptive technology. A screen reader, for instance, will read-- list seven items. So visitors using this technology have some idea of the length of the content they are about to browse through.

Numbered lists should convey an ordered value to its list items. Often, how-to articles are outlined in a set of steps. This is a perfect example of a reason to use a numbered list.

Bulleted lists should be used when there is no inherent order to your list items. When I look at this article, I can tell already that the sections below the headings are really meant to be ordered lists, or numbered lists. So I'm going to go ahead and select all of that content and just apply numbering to it. So click on the Numbered list button. And the same for down here.

However, there's a problem with this list, because in the text that was brought over by the Word document, I had already typed in "Step 1," "Step 2," and so on. The list itself applies the numbering. So I no longer need this text. Definitely don't want to be redundant. That's better.

Links and smart links. Do not open links in a new tab or window. Links opening in a new tab can be disorienting for people with low vision or who are navigating via screen reader, especially when there is no warning. Never use the full URL of the link in your text. Web URLs are visually messy and difficult to read. And screen readers will read every single character of that text out loud.

Use readable, descriptive text for the link. Avoid "click here" for links. Instead, describe the content you are linking to, such as "download the UMSO pay calendar." Pages with repeating content, like news articles, often use "read more" for each article. But people using voice control to navigate will not be able to activate the desired link if they are all the same text. And people using screen readers often use a shortcut to list links on a page. Imagine hearing "read more" over and over.

There are two links already included in the text that I brought over from Word. You'll note that it inserted the entire text and made it into a link. We don't want that. I'm going to look at the steps. And I think I need to change this a little bit.

It says, step one, "Go to the Slack Website." "Click on the Download Button." And step three, "Choose the Mac Version." I'm going to change this to-- removing two items and changing step one to "Go download the Mac version of Slack."

And I'm going to make that entire sentence the link. So down here, I can cut that text out and then select my text and use the Link button. You'll notice that there's another button right next to the main Link button. And that's called a smart link. We'll talk about that after I show you about links.

Click Link. Paste the full URL into the URL field. The Display Text is already filled in because I selected the text before I clicked on Link. If you had just placed a cursor and clicked on Link, you would have to fill this in manually.

The Title is not necessary. And Open link in is the next option. Notice that it's already set to New Window. That is not what we want. We want to make sure that this is set to Same Window. And click Save.

And do the same thing for the Windows download, cutting out that whole link, changing the top three options to "Download the Windows version of Slack." Selecting the text, hit Link. Paste the URL in. Check my display text. That is what it's going to be pointing to. And then open in same window. Click Save.

Now let's talk about smart links. I'm going to put a little bit of text at the bottom and say, "After installing, find out more about first-time login," because this is going to be a smart link that links to another article.

So smart links, they operate the same. And the box that is available right here says Link to Article. So I know that there is an article that's already in the knowledge base. And if I type just one of the words that's in the title, it does a search for me. First Time Login to Dropbox is one of them that comes up. First Time Login to Slack. There you go. That's the article that I want to link to.

The Link Text, if I don't fill this in, it defaults to the knowledge article title. And notice that the Target is not set. You can change this to Same Window. But since it's not set, it's not going to set it as a new window. And there we go.

Accessible images. Accessible images must include alt text. Alt text should convey the meaning or purpose of the image and convey details that a sighted user would glean from that image. If the important information about the image is already described in the text of the page, for instance, with a screenshot of a how-to step, it is acceptable to put "screenshot of step 4 described above."

Mark as decorative if the image truly adds nothing to the page experience. In Salesforce Knowledge, marking as decorative requires editing the HTML source code. Resize and optimize the photo for the web. The initial pixel size and the initial file size can be massive. There are tools to help you crop and resize an image and tools to reduce the file size even further. You should shoot for a file size below 100k.

So I'm going to add an image to step three of the Installing Slack for Mac section. It says "Open the Downloaded File." Right after "Open the Downloaded File," I'm going to hit Shift-Enter. That will give me a break instead of a whole new list item. If I were to just hit Enter, I would get a new list item. But I want this image to be nested below step three. So I do not want a full return. So Shift-Enter will give me a space to add this image.

So you can use this little button Image. Click on Upload Files. And in Downloads, I have this screenshot. Now, I have already resized this screenshot. When I took the screenshot, it was actually over 900 pixels wide. And that's just a little bit too large for the way that it will look on the knowledge base article page. So I downsized it to about 400 by 245.

And since it was just a screenshot, the file size is actually fairly small. So this is acceptable for an image to be placed on a website. So I'm going to click on that image, click Open.

And in the Alternative Text-- now, I did already describe what I want this person to do-- open the downloaded file. But that doesn't really describe what's going on in this image. So I'm going to type in a description about what I'm seeing in this image-- "the task bar with-- the Mac task bar with downloaded folder expanded and the downloaded file showing in the list."

Now, I think that looks pretty good. I think, though, I would like a little bit of clearance above and below the image. So I'm going to click right after "Downloaded File" and hit Shift-Enter to give it another break. And right after the image, Shift-Enter again to give it another break. That just makes it a little bit cleaner.

Accessible video embedding. Videos must include captions and should have a separate transcript. Autogenerated captions must be checked for accuracy. The deaf/blind community and individuals with an audio processing disorder will benefit from having the transcript in HTML format right on the page.

If the page that has the video embedded is already very long, it is reasonable to link to the transcript on a separate page. When the video hosting includes the transcript, such as on YouTube, it is fine to link to the video on that website with descriptive text indicating that you are linking to the video and transcript on another site.

Video iframe must include a valid title attribute that names and/or describes the video. The provided embed code does not always have this. And the HTML source code will have to be edited if it does not.

So I'm going to add a video to the Windows section because there is a YouTube video that might be helpful for people trying to install Slack on Windows. I'm going to put "Watch the YouTube video." And that text, since it's below the section for installing Slack for Windows, which already has a heading 2, I'm going to grab that text and make that a heading 3.

And below that, I will do my video embed. So my cursor is placed. You can click this Media button and Embed. And this is the box that we're going to use to place our embed code. So let's go over to YouTube and get that embed code. This is How to Install Slack for Windows video that I found. And I'd like to share this.

And I want the embed code. What I want you to take a look at, though, is this iframe and to notice that there is a title attribute right here-- title = "YouTube video player." So there's a title attribute, but it's still not accessible, because that is not the correct title for this video.

So I'm going to copy this. And I'm going to go over to my Installing Slack for Windows section, where I've already got the embed open. And I'm just going to do Control-V to paste that in there. Now, I do need to go through here and choose that title "YouTube video player" and change it to "installing Slack on Windows." That's the name of the video. And click Save.

So as of right now, this looks like I'm finished. However, if I were to save this and publish this article, this video would be enormous. It would take up the entire width of the page. So what we really need to do is apply a wrapper. So unfortunately, when you're going to put videos in, you are not going to be able to not edit HTML.

So you're going to have to click on-- this is selected already. But click on Source Code. And that's going to bring us into this very messy view. A quick way to find your images and videos and links, they're generally in red text. So if you don't want to try to scroll through all of this with your eyeballs, try to slide down to the bottom. And you'll see that h3 is the heading 3, Watch the YouTube video. And the iframe is here.

What we need to do is remove the paragraph tag before the iframe and remove the closing paragraph tag after the iframe. I'm going to show you the article that I've already written that describes this. Actually, I can just copy this-- div class equals "video-wrapper" and div class equals "video-container." They're nested within each other and wrapped around the iframe.

So I'm going to paste that above the iframe. And I'm going to grab this and paste this below the iframe. And that will make this a responsive video that limits its size. And click Save.

You're not going to see anything different when you're looking at it in the knowledge base editing tool. So don't worry about that. But when you browse to this, it will set this video to be responsive so that it is a nice size on desktop but also fits on all other devices.

Now, I did not mention the transcript. This video doesn't actually have a transcript. However, just for this example, we're going to say that it does. So I'm going to type in some text and then link to the video location so that people can get the transcript. "The full transcript for 'How to Install Slack for Windows' is available on the video page in YouTube."

And I'm just going to link "full transcript for 'How to Install Slack for Videos-- Slack for Windows.'" I'm just going to grab that bit of text and click the Link button to insert a hyperlink. I need to grab this URL. Paste that in. Highlight this text. And I'm going to hit Same Window and Save.

Making tables accessible. Never copy and paste tables from a spreadsheet or document. Use a converter tool to convert spreadsheet data to a clean HTML table. A link to a good converter is included in this course's resources.

Always include a header row. The table header provides the relationship between the data in the cells and label in the header row. Screen readers will reference headers as the visitor navigates through the content of the table.

Include a caption. Captions should identify the overall topic of the table. Captions can aid in the understanding of more complex data. Consider providing a download of the data. If the data set is very large.

Back at the knowledge article, I want to change this "Download the Mac version of Slack" link to a table of Mac OS versions that link to different Slack versions. So edit the article. And I'm going to expand it to full screen just to make it easier to see. And click on the link. Double-click it. And bring up the Link dialog box. I can take out the URL. And Save. And that will remove the URL.

And now I'm going to put a colon and Shift-Enter for a break. So in order to insert a table, you can use the Table button. And then in this first menu item, select the number of columns and rows that you want to insert. And that does insert a table fine. But what it doesn't do is add a header row.

So in order to add a header row, you'd have to edit the HTML in order to do that. So I would suggest that we do something different. I'm going to go over to my Excel file, where I've already created the table that I want to insert. And I'm just going to copy that.

So instead, we can use a table converter tool that I found online that works really great and allows you to set a table header as well. So you don't have to edit the HTML. So I can paste my content in here. And you'll see that it correctly configures this as an Excel. Any Excel table would look. And you can edit it here as well if you need to make changes to it.

And then if you scroll down, this little checkbox will change that top row. That's the first row. It changes it to include a thead tag. And then the rest of the content goes in the tbody tag. And the td cells change to th's. And that is what gets styled as the header row. But it also is what allows adaptive technology to let someone know where they're at in the table.

So once you have done your conversion, you can copy to clipboard. And that will copy all of this HTML for you. Then you can go back over to your knowledge article. And we've already added a break. So let me go into Source Code view, because you have to paste in Source Code view. So go into Source Code view. And you'll see that you added the break. I somehow added two of them.

You can do a hard return between the end-- the break tag and the closing li tag. Unfortunately, there's no other way to do this. You really just have to do this. And you can paste there. Save that. And then when you come back over here, you can tell-- it doesn't look the way that it's going to look once we publish it. But you can tell that this top row is considered a header, because it already looks different from the rest of the content. It's not how it's going to look when we publish it. But I'll show you that.

So if I close this and save and publish, let's go browse over to the article that I already had up. And I'm just going to clear out my cache and refresh. And now you can see the table. Our styling adds this darker blue background and a slight text shadow, with the text is much larger in the header. This uppercase is just a visually uppercase. It's not actual uppercase.

And then the content below is left aligned and has some nice padding. So this is how to get a really nice table.

Now, we also want to be able to add a caption. And unfortunately, you cannot add a caption without editing the HTML. I would recommend if you want to add the caption to actually add it here before you copy and paste this into your article. And unfortunately, there really is no other way than to type it in. So your caption tags are an opening caption tag and a /caption closing caption tag.

And then, "Click on the links to the version that matches your operating system." This is overkill. I would not include for this table. But this is how you would have to add that. So if you added it and then copy to clipboard and paste in just like we already did, that will include the caption.

Additional components to avoid. The editor in Salesforce Knowledge has additional components that we'd like you to avoid using. Accordion-- this has been tested and is not fully accessible in all browsers. Quick text-- this is not configured in our environment.

Code sample. A code sample creates a gray box of selectable text that can be copied. This should only be used if you are providing HTML code to be copied. Anchor. This is also called a bookmark, used to provide a link to a section of the page. It's only used for very long documents, and it's difficult to make accessible. It's probably unlikely to be used in a short knowledge article. Horizontal line produces a visible line on the web page. It's used as a thematic break in long documents and will be read by most screen readers as a "horizontal separator."

Thank you for attending this course. As always, if you have any questions or need assistance while creating your knowledge articles, you can contact the DX team. Thank you very much.