Accessibility issue

[zvi]

I pointed out a sort of overarching issue with the FAQ documentation as currently written to rho, and, in traditional DW fashion, she asked me to take the first pass at solving it.

The problem is that some of the documentation is written with visual, spatial, or movement-specific language. To the extent possible, FAQs/sitedoc should not be written with the assumption that the eventual reader is going to be seeing the same images and screen ratios, nor that they'll be interacting with their computer with the same input devices as the writer's. On the one hand, you have people with disabilities using the site; on the other hand, you have people with an array of mobile devices using the site; and on the third hand, you have a few people out there still cruising in lynx, because they're Richard Stallman. (Not to mention that we'll support different siteschemes, and people will do all manner of funky things with their journal styles.)

I'm going to do a first sweep through the FAQ docs as currently written, but I strongly suggest you guys hook up with the Accessibility team for more expert advice. (For instance, I am unsure about whether or not dropdown menu is a term that is meaningful on a screenreader.) My inexpert advice is that, wherever possible, instead of describing a visual element, you include the image and its alt-text as it will appear on the site (maybe with a note that it's the site default?), and if you can skip the visual element and just link to the thingy in question, that's even better.

By visuospatiai issue, I mean that the FAQ says "perform this motion" for interacting with the site, or "item found to the left of second item" or "choose the [textual description of image] to accomplish task" Any language which requires the user to be seeing the same site visually or using the mouse or keyboard like the writer.

Additionally, all link text should be meaningful ("Choose your sitescheme" instead of "click here to"), and, a title attribute should be set when the link text doesn't match the page title of the page the link refers to.

FYI Each tab of my account settings has a URL, so you can link directly to that tab.

( FAQ's w/ visuospatial language )

P.S. Psst. forthwritten. May want to include site-specific URL forms in What Dreamwidth specific markup can I use?. All the lj were replaced with site.

Going forwards with userdoc

[rho]

Please sit down and take out your paper bags to breathe into before reading any further. You just might need them.

It's April 2 today, which means that we have exactly four weeks until open beta and four weeks to get our FAQs and guides into a state suitable for open beta consumption. There are already a lot of people asking questions, and I'm seeing our FAQs getting linked to in the wild, so I want to try to make sure we have some awesome documentation before open beta launch.

Ideally, I'd like to try to get everything finished up at least a week in advance (ie, by the 23rd) to give us time for proof reading, testing, checking for accessibility and so on. If we aim to finish early, that also gives us a little bit of wiggle room for when things inevitably run over a little. This gives us three weeks.

I'd appreciate it if everyone on the userdoc team (those of you writing FAQs and guides) could either comment here or email me to let me know what you're working on, how you're getting on with it, whether you're going to be able to finish on time or whether you'll need help, and whether you'll be able to take on additional tasks after you've finished what you're doing at the moment.

If you al can do that for me, that will let me plan out our final push to the finish line.

The deep magic of [[brackets]]

[rho]

There's been some confusion as to how things in [[brackets]] work in the translation system, so I'd like to try to clarify.

In the code for a BML page, there are references to all the translation strings, which basically mean "when you get to this point in the code, look up that text of the translation string, and put it here". In the code, there can also optionally be a way to pass a variable to the translation string. Let me try to explain.

In the code, there might be a variable called $username, which contains the username of some account that we're doing something with. We might want to have a sentence like "Add $username to your access list". We could do this by making "Add" be one translation string and "to your access list" be another, and putting our variable in the middle but this is all sorts of bad and messy and likely to lead to strife. So instead, what we do is tell the code to write out some translation string except that when it encounters [[user]] in the translation string, it replaces it with whatever the code has in $username at the moment.

As such, things in brackets will work only if the code has been explicitly written to allow them to work in a given translation string. In our example above, we couldn't then use [[user]] in some other translation string as the code wouldn't be expecting it. We also couldn't change [[user]] to [[lemming]] and expect it to still work. It will only work with the exact right word in the exact right translation string.

Non-technical summary: Things in [[brackets]] are deep magic. If you see them, don't touch them. Don't try adding them in yourself, because it won't work.