Welcome to Make Things Accessible

In order to contribute to our site, you would need to receive an invite, so you can login to our Content Management System, if you haven't yet received one and are part of the UK education sector, please send an email to [email protected] along with a few details:

• Your first and last name (required)
• Your job title (Optional but strongly recommended you do provide it)
• Your organisation (Optional but strongly recommended you do provide it)
• A short bio, just tell us a bit about your experience and help users get to know you a little
• A profile picture (optional and ideally this would be square 192 * 192px)
• Optional contact methods are:
  • Your Twitter handle
  • Your LinkedIn
  • Your email
  • Your website if you have one

Once you send us all of those, we can create you a user account, so the guides you create are attributed to you. Just a quick heads up, we are very fortunate to have our hosting provided to us for free, by the awesome folks at Netlify and a condition of our free Open Sorce account is that we provide information on a non-commercial basis, so please ensure:

• You do not canvas for work
• You do not promote goods or services as part of any paid promotions

It's fine to discuss software, courses and assistive tech, but not for monetary or personal gain.

How to create guides in the CMS

Upon logging in, you will be presented with the primary CMS screen which contains 2 important links in the header (top) area: Contents and Workflow.

The Contents link is where we create content for our website, within the Collections panel we would want to ensure that Guides is the active option and then we would be presented with a list of all guides in the CMS and also a New Guides button, clicking this button will take us to the CMS where we can create a guide.

There are several fields we must fill out before we get down to actually writing our content, we'll explain best practices for each, to help you quickly get to the content you want to write.

Title

This is the title of your guide and also what will appear on search engine results, keep this to a reasonable length and ensure it's meaningful, this will help with discoverability for search engines, but primarily it will provide site visitors with a good indicator of the guide topic. Your Guide title will need to be unique, so please ensure you do not create a guide with a title that already exists in the system, as this won't post, as the URL for that page is derived from the Guide title

Summary

This should ideally be 2 or 3 sentences, further explaining the topic of the Guide, this will be displayed on the card panel, along with the title and author, this is also displayed on a search engine result and ideally should be about 160 characters in length.

Author

Prior to being sent a request, you will have been added to the author's list, this is a Select input, you simply select your name from the list of options within

Table of Contents

This toggle switch is off by default, so no table of contents will be displayed, we should only add a table of contents where we have 4 or more Heading 2s in our Guide content, if you have 4 or more, then toggle this switch and a table of contents will automatically be generated for you

Tags

A Guide must have at least 1 tag and it should not ever have more than 5. Tags help users find related content in the system or search by a particular topic. At present, there is a potential issue with tags, that you need to consider before adding them. If we create a tag that already exists in the system but does not exactly match the case (lowercase uppercase), this will cause a publishing error and your guide will not be published. This will be resolved at a later date, but in the interim, visit https://www.makethingsaccessible.com/guides/ and open the Filters accordion, all current tags are available there, if using a tag that already exists, ensure that it is typed exactly as displayed in the Filter by tag section. You can of course create a new tag, but please ensure that the spelling and case is correct when you do, as an example WCAG (All capitals), PHP (All capitals).

There is an Add Tags button, which when clicked will expand the panel and reveal an input, this is where you type your tag name. To add another, simply click tha Add Tags button and an additional input will be revealed.

Include Files

Should you wish to include a document on your Guide, it is necessary to upload it using this option, so you would click Choose Files and then you would likely want to choose Upload, which would upload from your device. Please ensure your file has a unique name, as this will cause an issue if it's non-unique, fortunately, all the documents are saved in the same folder and they are presented to you in the dialog for files. Uploading a file does nothing more than store it in the documents folder, so there is one more step to take. Once the file you wish to add is within the folder, simply select that file and then click the "Copy Path" button (this would have previously been disabled/greyed out). Now the file path is saved to your clipboard, so highlight the text you wish to act as the link, select the "link" option in the editor's toolbar (visually, this is two segments of a chain). A dialog then opens with a single input, you just need to paste the contents of your clipboard into there, in your usual way (some common methods are below:

• CTRL + V (Windows)
• CMD + V (MacOS)
• Right click and select "Paste" (Windows and MacOS)
• Long press and select "Paste" (Android and Apple touch devices)
• Or however you would usually paste copied content

Finally, click "OK" in the dialog and your link to the file is complete

Creating page content

Finally, we have our required fields set, so now we can look into the editor, this is going to be similar to what many of you have encountered before on other CMS sites, such as WordPress etc. It's not as fully featured as many common CMS editors, but we can extend it and we are trying to make it more user friendly in places, especially for the new options we have created.

Using the editor

We use Netlify CMS, which serves our needs and Netlify have kindly sponsored us to have free hosting, what an awesome bunch, right? The editor is both Rich Text and Markdown, you can simply toggle the switch to change your preferred input, I persoanlly use a combination of the two, as there are sometimes some features not available in the Rich Text editor and the Markdown editor lets me write HTML too.

So, first things first there are 9 buttons in the toolbar of the editor, which should be familiar to many of you, but I'll list them here:

• Bold, for bold text
• Itallic, for itallic text
• Code, this is for inline code, a small piece of code that does not appear in a standalone block like so <h1>
• Link, for creating a hyperlink
• Headings, for section, subsection etc, headings
• Blockquote, when we quote something somebody else said, we use a blockquote
• Unordered list, a standard bullet list, we can further indent by using the Tab key
• Ordered list, again we can further indent with the tab key
• Add Component, this is where additional blocks reside, I'll explain these in detail, shortly, as there are 1 or 2 caveats

When creating a guide, please don't use a Heading 1, your post title is marked up as the Heading 1, the title of the page, so you just need to use Heading 2s for sections, Heading 3s for subsections and so forth

Using the editor block components

Clicking the Add Component button will display a list of additional tools, we careted a few and Image and Code Block were already present, out of the box. We'll discuss thos first:

Image

We may want to add images, we select Image and a Block appears in the editor, we then select Choose an Image and either select an existing image or upload from our device. Once the image is uploaded, ensure it is the selected option, when you upload the image, it's the automatically selected one.

Sadly the ability to upload an image doesn't appear keyboard accessible. This is the core Netlify CMS, so I'm not totally sure how to fix that, but rest assured, we'll definitely look into it and ask about.

Quick tip: If you're using a Mac, please rename your file before uploading, especially if it's a screenshot, as Netlify doesn't like the default filenames for Mac screenshots. We really should be giving every image a unique name, as we don't have any backend logic to handle clashes.

So, just to recap:

• In the Add Component button's expandable options, select Image
• Click the Upload button
• Upload your image
• Click the Choose Selected button
• Your image will now appear in the editor, where you can add your alt text, ignore the title attribute though

Code Block

A code block is for giving more detailed code examples, as opposed to a small inline piece of code, these are standalone blocks, that appear in what looks like a code editor, you can either type your code directly into the block or paste it in. Just one thing we need to do first, to ensure the correct formatting takes place, is we need to click the cog icon (sadly this doesn't have an accessible name, meh! but I will look into that, but it's core Netlify stuff, so may be quite difficult for me to fix).

Upon clicking this unnamed button, we have access to some options, the only one we need to change is the first Select input, which is the Mode options. We simply need to select the language of our code, we're only typically going to be using HTML, CSS and JavaScript, so select the option which is most appropriate from those. If you have just one file, with HTML and any of the other options, the file should always be HTML and appropriate <script> and/or <style> tags should wrap the JS or CSS, respectively.

Callouts

There are 3 types of callouts, one for a tip, one for info and warn for a warning:

• A tip callout should be used when you wish to provide a tip that relates to the current topic, as an example of when to use a Tip, assume we are writing about testing with the Axe browser extension, we may want to add a tip that says "Test the page with Axe and check the results, now open the modal and run Axe again, as it will not be able to identify issues that were previously hidden". You can of course use the Tip Callout for anything that makes sense, keyboard shortcuts, best practices, techniques, quirks or whatever else would be considered a helpful tip.
• An Info callout should be used to provide some additional info, that you would like to make users aware of, for example, if we were writing aboit using a screen reader and we were aware of a bug with a specific screen reader and browser pairing, you may wish to use the Info callout for that information, there are multiple scenarios for Info Callouts, mentioning a regulation, a software or hardware limitation, bugs, shortcuts or alternative techniques etc.
• A Warning callout is for something that could potentially be a bad practice and harm a user, prevent them from completing their task, make something difficult for them and even things that could affect your employer, such as failing to make things accessible could get you in a lot of troble and cause reputational harm

Accordion

We all know what an accordion is, right? For those that aren't familiar with the term, it's essentially a way of hiding some content until a user interacts with it. There are valid reasons we may want to use an accordion, we use them in the FAQs page, to help users find what they're looking for easily, we also use them in guides, from time to time, if we want to digress a little from the main topic, if we wanted to reveal answers to questions or we may be inclined to add some technical information in one of those, that wouldn't necessarily be relaevant for everybody that is reading that particular guide.

There are some things to be aware of when using an accordion, which I'll explain below:

The accordion block takes 3 inputs:

• A Heading level, it has a sensible default of 3, but it could be 2, 3, 4, 5 or 6, depending on where you use it and your page hierarchy, please do ensure it has the correct level, as we know all too well our users appreciate a heading hierarchy
• Title, this is the heading text, you selected the level with the previous step, now you simply add the text. try to keep it short and to the point
• Content, the content can be anything really, but please don't nest accordions, as 1 level of hiding stuff is quite enough. You can use the Rich Text editor in here, so you can add text, links, images and whatever else you need to hide from initial view.

Our accordions are progressively enhanced, that means that as an author, all you are creating is a heading and a container to hold your content in, if a user does access your content without JavaScript enabled, they will get the Minimum Viable Content, the heading and some associated content. There's a bit of magic that goes on behind the scenes, which enhances that heading and content to be an accessible accordion, you don't need to worry about that though, as this happens automagically.

Quick side note. When you initially create an accordion, it will be the blocks, if you save your page and come back later, you will see raw HTML in the rich text editor, this doesn't mean your accordion is broken and won't display correctly, it just means I have to figure some stuff out to keep it looking nice for us authors. If you do need to change anything, you would change the Title only between the <h#> [Your title] </h#> where the # represents the heading level 2 - 6, depending on your usage and the actual content would be between <div class="accordion-panel"> [Your content]</div>. This is something to be aware of, I'll get it fixed as soon as I can figure it out and I get the time.

Transcript Container

This should only be used directly after we embed a YouTube video and it should contain the transcript to the video. Much like the accordion, it's an expando widget, but this one uses the native HTML Details element, it must come directly after the video, so our users that need it can find it with ease and our users that need it don't have to scroll through a million lines of George talking about accessibility statements (Sorry, George)

How do I add a video, you may ask? Well, currently we need to go to YouTube and get the video we wish to embed and:

• Select the Share option
• Select the Embed option
• Check the "Enable privacy-enhanced mode" checbox (block those pesky cookies)
• Click the Copy button
• Return to Your Guide you are creating and toggle the switch to Markdown
• Paste from your clipboard the iFrame from YouTube in a suitable location
• Switch the toggle back to Rich Text
• Now Select the Transcript option from the Add Component button
• Copy your Transcript from wherever you have it and paste it in to the Details Editor
• If you only have one video on the page, there is no need to change the text in the Summary input, if you have more than one, just make sure each are specific

Much like the Accordion, this will display a block, but if you save and revisit, you will see raw HTML, I know, you're wondering if I even know what I'm doing, right? Don't worry, I'll get these fixed as soon as time permits, but at least we have those options right, even if they have little bits of snagging that need attention.

The Editor and Preview panes

All along we have been explaining how to create content in the Editor pane, you may have noticed there is another pane, too? This is the Preview pane and it gives a rough idea of what your content will look like, it's not styled exactly the same as our website, this is something we will add in later, but it's not as important as some other aspects. Rest assured, your content will look nicer in the live or preview views.

Saving and Publishing

So, you have written your content and you want to publish it or get somebody to review it. At the top of the interface, there is a Save button, which as you may have already guessed, saves your content, first we need to hit that button, so we can progress.

Now once that has saved, which takes a few seconds, 4 new buttons appear:

• The first is the Status and is a expando button, clicking it presents us with further options to change the Status of the Guide
  • Draft (default): It's just saved to our GitHub
  • In review: You want somebody to check it before publishing
  • Ready: You want to get it out there
• Publish, which is also an expando button, but Publish Now is the only option that matters here
• Delete Unpublished Entry, which will obviously delete you guide
• Check for preview, this is where you can see a live preview of your page, on the Make Things Accessible site, it's not actually on the site, but a clone has been created to preview your guide, you can of course share that link if you want somebody to check it over

If you want to publish, after saving you should change the Status to Ready and once that action is complete, then expand the Publish button and select Publish Now, it takes about 20 seconds for your guide to be live, as there is some wizardry happening in the background, most of which is related to the tools we use doing the heavy lifting for us

Editorial Workflow

If you just Publish your guide, this isn't really relevant, as your guide won't appear here. If you just save it, it will be assigned an Editorial status, the default being Draft, which you can change to either In Review or Ready. I guess the concept is, you change to In review, let your chosen reviewer know it's ready to be reviewed and once it is, they would then change the status to Ready, so you could publish it.

We're not enforcing any kind of workflow here, if your guide is accurate and ready to go, publish it, if you want someone to review, you can send them the link from the Check for Preview page or just get them to locate it in the Workflow page, your choice.

The Workflow page is accessed from the Home page, to get back to the Home page, after your content is saved, the link in the Header should say "Writing in Guides Collection, Changes Saved", clicking this will take you back to the Home page.

We previously discussed the Contents tab, within the Header, now we will touch upon the Workflow tab. If you save your guide and do not publish it, this is where you will find your guide and all others that other folks may be working on. There are 3 columns for the status and the status can be changed by clicking the Entry and using the Status and Publish options that were previously explained.

So if you have agreed to review an unpublished guide or you want to hold off on publishing yours, this is where you will find them.

Editing your Information

You may want to edit your information, from time to time, new job, new skill edit, add or remove socials, well you can do all of that from the Authors page.

Access and Assistance for All Guidance

After being invited via email you may edit the AAA content, following the guidance above. There are a few small differences for your content which should be understood prior to creating new content.

By clicking on the "Contents" tab within the CMS, there are two options for AAA at within the "Collactions" panel, the options are "AAA Pages" and "AAA Stories".

AAA Pages

This option contains the core pages "AAA Home" your Home page, "AAA Roles" the role-specific guidance you provide, "AAA Assistive Tech" the information you provide on assistive technologies and "AAA Supporters" a page where a linked logo of each of your supporters can be edited.

Guidance for adding a supporter must be followed, as adding any content other than images will cause the layout to break. Only images should be added to this page and each image requires a URL to the supporter's Home page (or other appropriate page).

To add a Supporter please follow these steps:

1. Click an appropriate place in the CMS editor (Any white space between/before or after existing supporters' blocks), to position the cursor at that point
2. Click the button in the editor that is visually identified as a plus icon with a small down-facing triangle (the accessible name of this button is "Add Component"
3. Select "logo link" from the Menu that opens as a result of clicking the aforementioned button
4. You will be presented with a block at the point where your cursor was positioned (Component block) which contains three fields
5. All three fields are required, the "Site URL" Field should be a link to the appropriate page of the sponsor, the "Alt Text" Should simply be the name of the site (as this is a functional image), as an example the Thomas Pocklington Trust logo simply has the Alt Text "Thomas Pocklington Trust", which is all that is required (if you need to link to a specific page on a supporter's site, you can of course append that text to something more specific if you feel it is helpful
6. The Image field links to the AAA media gallery where only AAA assets are present, you can upload new images or select existing images. We do require that you ensure images are a reasonable size before uploading, the maximum rendered size of an image is about 200px, so please do resize any images to that height before uploading, as high-resolution images will cause performance issues, there are multiple options to a resize an image, some operating systems contain built-in software to do this, Photoshop and similar and there are multiple online tools that are free to use (Search "Image resizer", logos should be uploaded in .png format

To upload an image click "Choose an image" from the Image field, a dialog will appear which displays the assets stored and several options. To use an already stored image, simply click the image and then click the "Choose selected" button.

To add a new image, click the "Upload" button and upload a file from your device in the usual way. This option should be auto selected once it has uploaded, then simply click the "Choose selection" button to add that image to the block.

Note Do not worry that the layout of the images is different in the CMS than on the website, this is purely to show they are present, they will display according to viewport size/pixel density/zoom level, using CSS flexbox on the live site.

All information necessary for images is available further up the page or you can click this link, for images guidance.

Should you need to add files to any of your pages, the process is exactly the same as The Include Files guidance, documented earlier, although you have your own AAA document folder. A quick recap would be like so:

• Adding a file is optional, if you wish to add one, click the "Choose files" option, from the "Include files" field
• If the file you wish to link to is not present in the folder, then you will need to upload it, by clicking the "Upload" button and then following the usual steps for file upload that is set by your operating system
• Once the file is present in the folder, simply select it (Unfortunately, his does not appear to work with keyboard, at present, we will raise an issue for that), once selected, click the "Copy path" button (this button was previously greyed out/disabled and was called "Copy")
• Close the file upload dialog
• Highlight the text you wish to add the file link to, example 'Read our charter', then you can either click the link icon (accessible name 'Link') in the CMS's toolbar or use a keyboard shortcut such as CTRL + K or CMD + K (or long press on mobile) and then paste the contents of your clipboard into the field and press Enter or click the "OK" button and your file is now linked to the text you selected