Readability and accessability suggestions for docs

I didn’t want to create a separate thread for each issue as they are similar and minor. So here’s a list of suggestions:


  • Installing CP guide in the first paragraph has a weird break for the note. I would recommend just making the note into its own paragraph.
  • Overall, the width of the content is a bit too wide. If we don’t plan to add any sidebars, we should reduce the width so it’s easier to read. It’s 940px right now, I would bring it down to 700px max. Although for accessibility, W3 recommends 80 characters.


  • Custom login image guide has images with missing ALT tags
  • CP is more accessible than WP at this point, so we need to keep accessibility in mind for everything we do especially docs.
  • On the homepage, Skip to Content doesn’t work because there is no #main container.
  • On code reference single posts, the search isn’t accessible by keyboard because it’s a div. Either we need to make div accessible as a button or make it into a <button> or <a>.


  • I noticed external URLs have no target set. I would recommend using a blank target for external URLs. We just need to provide advance warning to users for accessibility, which can be done with CSS.

Edit: Updated items based on the feedback.

1 Like

Agreed, well, actually, I’d take it down to 700px.

Ironically, on a page that completely fails to follow its own stipulation!

Actually, they aren’t missing. They are empty. There is a difference. Empty is fine, in principle, for accessibility. But, in this case, I agree the alt tag should read something like ClassicPress Login Screen.

Your other points are great, but I strongly disagree with this one. This creates an accessibility nightmare, and then tries to mitigate it with a warning. But it would make returning back to the CP site very hard because it renders the Back button useless. Hyperlinks should use the same tab by default to avoid this problem.

How do you figure that?

These are theme issues. Is the current theme the one that will be used, or is another being considered?

Best practices say that using a target is worse. Let the user decide if a new window is used.

Agree completely!

CP doesn’t have block editor.

@timkaye good points.

1 Like

Ah, but the Classic editor isn’t all that accessible either. They do have a team of people improving the a11y (a bunch was in WP 5.3), and CP has not incorporated all of those changes although some PRs were submitted recently.

This thread is related to docs readability and accessibility, let’s keep this thread related to that and not core. If there is anythings specifically missing is core please open a thread in that respective category.


That’s my fault, actually. When I was pulling up the reference, I grabbed the draft version. For some reason it’s the #1 result in Google. A better reference is WCAG 2.2 draft from this year:


I have put this on my todo list as it needs some server changes (CSS, HTML are both on the server)

About the search, that could take some time and testing, but makes sense of course.

About content editing, anyone with access can make those changes.
(Currently I think 5 people already gave content editing access). I think you can contact me or Wade to get an Editor access to the site. There should not be a high number of Admins, for obvious reasons.

Image - true, not only alts missing, but some docs still point to GitHub Content (Images) which needs to change.
I think also this can be done by any Editor role.




Fixed, and image centered.


I have submitted a pull request to add this to the home page template.


I’ll add this asap to the site (tomorrow first thing)
It will affect the look thou, due to CSS applying to #main as well. But as far I could see it is not even that bad, it makes the “sections” stack by 2 a row, which at first seemed a bit narrow but on a second look probably is not the worst.

(There is currently no sync yet between the 2 instances GitHub and site, so until that is done we first add to site, then James ports to git. Unconventional, I know :slight_smile: )

Yes, that’s exactly what it will do. Not sure if it will force content to left but, if so, we can just add margin: 0 auto; to correct that.

1 Like

Submitted pull request to change this to a button.

1 Like

This had some sideeffects on the looks of said “button”.
It needed a bit of CSS to bring it back to previous look, but is done now on live.

Looks like it’s working now.

I think the new width is ideal for things we need to read (posts, speak: user guides, developer guides, plugin guidelines)

It is suboptimal for single code references.
As said elsewhere :slight_smile: I am totally understanding that we need to set a container but there is also a weird hype of buying large screen machines and then still reading content on sections less wide than a number of phones nowadays available.

Why can we not use that space? Specially for code it is very annoying to have “narrow” sections.

I would if everyone agrees revert the width to the previous, on the code ref’s
In articles such as posts (guidelines in our case) I totally agree that too wide is tiring for the eye and diminishes the attention.
But for code it is the opposite, when I have to scroll vertically and horizontally it is distracting and doesnt help the understanding process.

What is the intake on this?

Yeah, that code view isn’t really usable.

You also have the choice of reducing the font size for <code> tags.

1 Like