Using Security keys on Codeberg #367

Copy link

n0toose commented 2023年11月10日 12:23:05 +01:00

Using the text itself (and not seeing the picture) does not help me figure out what I'm supposed to be seeing. You say that the user should go to "User Settings", but when I open up the settings, there's no section that says "User Settings" - there's this section instead: https://codeberg.org/user/settings/keys

My tip would be to explain everything as if the reader is five years old or not very technically competent to work around the UI. These, of course, are not very reasonable assumptions to make, but such a hold-me-by-the-hand writing style helps you become descriptive enough so that a blind person or a person that is, say, on 2 hours of sleep and running solely on caffeine, could work with that. Plus, you might avoid situations where a user would accidentally land on https://codeberg.org/user/settings/keys (as I did during the review :D).

---

I would enter some text telling people where to look for - along the lines of "Go to Settings and then head to the Security section", and then change the alt text to something like "Screenshot of the SSH / GPG Keys section" - holding the reader by the hand may seem redundant, but it would help both blind and non-blind users.

Same goes for Step 2. "Give your key a name" is a bit too ambiguous, you could say something like "In the Security settings, you should be able to find the "Security Keys" section, where you can add your key. First, give your name..."

Using the text itself (and not seeing the picture) does not help me figure out what I'm supposed to be seeing. You say that the user should go to "User Settings", but when I open up the settings, there's no section that says "User Settings" - there's this section instead: https://codeberg.org/user/settings/keys My tip would be to explain everything as if the reader is five years old or not very technically competent to work around the UI. These, of course, are not very reasonable assumptions to make, but such a hold-me-by-the-hand writing style helps you become descriptive enough so that a blind person or a person that is, say, on 2 hours of sleep and running solely on caffeine, could work with that. Plus, you might avoid situations where a user would accidentally land on https://codeberg.org/user/settings/keys (as I did during the review :D). --- I would enter some text telling people where to look for - along the lines of "Go to Settings and then head to the [Security section](https://codeberg.org/user/settings/security)", and then change the alt text to something like "Screenshot of the SSH / GPG Keys section" - holding the reader by the hand may seem redundant, but it would help both blind and non-blind users. Same goes for Step 2. "Give your key a name" is a bit too ambiguous, you could say something like "In the Security settings, you should be able to find the "Security Keys" section, where you can add your key. First, give your name..."

YellowComet commented 2023年11月12日 12:24:04 +01:00

Hmm, so:

1. Introduce a step between one and two indicating that you should go to the security settings, with an image similar to the one used for TOTP (df95d70243/assets/images/security/2fa/security-settings.png)
2. Change the alt text to "screenshot of the Security Keys section", maybe? I'm not a screen reader user, so I don't know what the appropriate alt text would be.
3. Add some text on the currently step two guiding the user towards the Security Keys section of the Security tab.

Did I get that right?

Hmm, so: 1. Introduce a step between one and two indicating that you should go to the security settings, with an image similar to the one used for TOTP (https://codeberg.org/Codeberg/Documentation/src/commit/df95d702437d0d69501e4684d06445dd754cdf74/assets/images/security/2fa/security-settings.png) 2. Change the alt text to "screenshot of the Security Keys section", maybe? I'm not a screen reader user, so I don't know what the appropriate alt text would be. 3. Add some text on the currently step two guiding the user towards the Security Keys section of the Security tab. Did I get that right?

n0toose commented 2023年11月12日 14:27:09 +01:00

I'm not a screen reader user, so I don't know what the appropriate alt text would be.

Introduce a step between one and two indicating that you should go to the security settings, with an image similar to the one used for TOTP

Change the alt text to "screenshot of the Security Keys section", maybe? I'm not a screen reader user, so I don't know what the appropriate alt text would be.

TL;DR: You are on the right path, but use text first, then add the image. The solution is more free text holding the user by the hand.

What I'm looking to see: Just, "Go to Settings, and then click on Security over at the bar on the left side of your screen" (the wording isn't exact - some other document may prove to be more helpful). You could make this easier for the reader (and maybe get away with not mentioning where exactly, i.e. left menu bar, they have to click) by adding a direct link to "Security", and then telling the user what they have to look for in that page. If you reach that point, changing the alt text (as described in 2.) should be OK.

---

Additional details about why I feel like this could be improved (feel free to ignore): The problem isn't 100% the alt text itself, it's that, put simply, you're relying on an image in order to send a specific message (that I'll refer to as "providing context") to the reader. This is not wrong, pictures are helpful for assisting a user. But there is a problem with the execution:

• The context you're trying to provide is lacking. As I understand it, the purpose of using that image is supposed to help the user verify that they are looking at the right thing, but doesn't describe how the user is supposed to get there. It helps users compare the actual Settings page and with the picture - that's its intended purpose.
• Read the Markdown file without the picture - try simulating "blindness". Does the picture (and its alt text attribute) help you make that comparison now?

Excellent alt text would mention details like the title, that there is an input box for inserting something, and a big button at the bottom right of the image - but as long as you do not solely rely on that picture to convey what you need to convey, this is not necessary.

My definition of blind does not include people that always have to rely on screen readers, but it also includes users of, say, hypothetical internet connections that are super weak. When I review a change, I deliberately just look at the "Files Changed" and just read the Markdown file as a text first and foremost. That's where I'm coming from, it may help you see what I'm talking about.

> I'm not a screen reader user, so I don't know what the appropriate alt text would be. > Introduce a step between one and two indicating that you should go to the security settings, with an image similar to the one used for TOTP > Change the alt text to "screenshot of the Security Keys section", maybe? I'm not a screen reader user, so I don't know what the appropriate alt text would be. **TL;DR:** You are on the right path, but use *text* first, ***then*** add the image. The solution is more free text holding the user by the hand. **What I'm looking to see:** Just, "Go to Settings, and then click on Security over at the bar on the left side of your screen" (the wording isn't exact - some other document may prove to be more helpful). You could make this easier for the reader (and maybe get away with not mentioning where exactly, i.e. left menu bar, they have to click) by adding a direct link to "Security", and then telling the user what they have to look for in that page. If you reach that point, changing the alt text (as described in `2.`) should be OK. --- **Additional details about why I feel like this could be improved (feel free to ignore):** The problem isn't 100% the alt text itself, it's that, put simply, you're relying on an image in order to send a specific message (that I'll refer to as "providing context") to the reader. This is not wrong, pictures are helpful for assisting a user. But there is a problem with the execution: - The context you're trying to provide is lacking. As I understand it, the purpose of using that image is supposed to help the user verify that they are looking at the right thing, but doesn't describe how the user is supposed to get there. It helps users compare the actual Settings page and with the picture - that's its intended purpose. - Read the Markdown file without the picture - try simulating "blindness". Does the picture (and its alt text attribute) help you make that comparison now? Excellent alt text would mention details like the title, that there is an input box for inserting something, and a big button at the bottom right of the image - but as long as you do not solely rely on that picture to convey what you need to convey, this is not necessary. My definition of blind does not include people that *always* have to rely on screen readers, but it also includes users of, say, hypothetical internet connections that are super weak. When I review a change, I deliberately just look at the "Files Changed" and just read the Markdown file as a text first and foremost. That's where I'm coming from, it may help you see what I'm talking about.

n0toose commented 2023年11月18日 23:15:02 +01:00

Hi, I am afraid that I may have accidentally scared you away by leaving such a large response (with good intentions, I'm working on improving explaining my own perspective with less words) or that I may have accidentally given you the impression that I am requesting a lot.

Either way, I'd like to help with bringing this in a merge-able state while respecting the fact that you are also doing this in your free time. You can contact me if you want to request some opinion from me in real time (for reasons of speed) or if you want me to take over.

Hi, I am afraid that I may have accidentally scared you away by leaving such a large response (with good intentions, I'm working on improving explaining my own perspective with less words) or that I may have accidentally given you the impression that I am requesting a lot. Either way, I'd like to help with bringing this in a merge-able state while respecting the fact that you are also doing this in your free time. You can contact me if you want to request some opinion from me in real time (for reasons of speed) or if you want me to take over.

YellowComet commented 2023年11月19日 00:31:58 +01:00

Hi, I am afraid that I may have accidentally scared you away by leaving such a large response (with good intentions, I'm working on improving explaining my own perspective with less words) or that I may have accidentally given you the impression that I am requesting a lot.

Don't worry, you did not :). I've just been busy lately, IRL stuff taking me away from the computer and all that.

Either way, I'd like to help with bringing this in a merge-able state while respecting the fact that you are also doing this in your free time. You can contact me if you want to request some opinion from me in real time (for reasons of speed) or if you want me to take over.

I'll be sure to let you know if I need help with this, thanks!

> Hi, I am afraid that I may have accidentally scared you away by leaving such a large response (with good intentions, I'm working on improving explaining my own perspective with less words) or that I may have accidentally given you the impression that I am requesting a lot. Don't worry, you did not :). I've just been busy lately, IRL stuff taking me away from the computer and all that. > Either way, I'd like to help with bringing this in a merge-able state while respecting the fact that you are also doing this in your free time. You can contact me if you want to request some opinion from me in real time (for reasons of speed) or if you want me to take over. I'll be sure to let you know if I need help with this, thanks!

YellowComet commented 2023年11月21日 16:37:10 +01:00

@n0toose Please see 1080442353 and let me know what you think.

@n0toose Please see 1080442353 and let me know what you think.

n0toose commented 2023年11月10日 13:26:44 +01:00

Our Style Guide also suggests using admonition boxes. This hasn't been applied to past changes retroactively, but we prefer them for new changes.

If you are not sure how to use admonition boxes, I'm leaving this change as an example: #355/files

Our [Style Guide](https://docs.codeberg.org/improving-documentation/style-guide/) also suggests using admonition boxes. This hasn't been applied to past changes retroactively, but we prefer them for new changes. If you are not sure how to use admonition boxes, I'm leaving this change as an example: https://codeberg.org/Codeberg/Documentation/pulls/355/files

YellowComet commented 2023年11月12日 12:06:36 +01:00

Done in d8bc110

Done in d8bc110

n0toose commented 2023年11月12日 13:58:41 +01:00

Thank you!

Thank you!

Copy link

n0toose commented 2023年11月22日 15:42:28 +01:00

tiny nitpick: capitalize "User Settings", maybe add hyperlink to user settings (low priority

tiny nitpick: capitalize "User Settings", maybe add hyperlink to user settings (low priority

YellowComet commented 2023年11月25日 16:48:36 +01:00

This section is a copypaste from the TOTP section 1 above. If you want to have this link to https://codeberg.org/user/settings should I also add this change to the TOTP section?

This section is a copypaste from the TOTP section 1 above. If you want to have this link to https://codeberg.org/user/settings should I also add this change to the TOTP section?

n0toose commented 2023年11月26日 18:56:04 +01:00

Yep, both places would be great. First method would be better, and would circumvent the need of having to be overly descriptive when the user can just "click on the picture" and see it for themselves.

Yep, both places would be great. First method would be better, and would circumvent the need of having to be overly descriptive when the user can just "click on the picture" and see it for themselves.

n0toose commented 2023年11月27日 01:00:16 +01:00

I will add more explicit Style Guide instructions and check where I can fix similar instances of this in a bit - I apologize for the yak shaving. Even though you wisely chose to compare against "what others did before you" in order to make your change as compatible as possible, unfortunately, not all written documentation adheres to the Style Guide very well.

I'm trying to strike some sort of a balance between not "punishing you" for doing that to the detriment of not following the "Style Guide" by the word myself (with the hopes of being able to clean up some formatting issues during a clean-up), as well as trying to address some minor fixes that could make further iterative fixes easier.

I will add more explicit Style Guide instructions and check where I can fix similar instances of this in a bit - I apologize for the yak shaving. Even though you wisely chose to compare against "what others did before you" in order to make your change as compatible as possible, unfortunately, not all written documentation adheres to the Style Guide very well. I'm trying to strike some sort of a balance between not "punishing you" for doing that to the detriment of not following the "Style Guide" by the word myself (with the hopes of being able to clean up some formatting issues during a clean-up), as well as trying to address some minor fixes that could make further iterative fixes easier.

YellowComet commented 2023年11月28日 09:31:08 +01:00

@n0toose TOTP section 2 also is just an image with no text. I think this should be left for another PR to address, this one is kinda going off mission I think.

Edits from maintainers are enabled tho if you want to handle this here.

@n0toose TOTP section 2 also is just an image with no text. I think this should be left for another PR to address, this one is kinda going off mission I think. Edits from maintainers are enabled tho if you want to handle this here.

n0toose commented 2023年11月28日 21:56:32 +01:00

You're right, approving.

You're right, approving.

n0toose commented 2023年11月22日 15:41:48 +01:00

nitpick: typo, it might be best to put a hyperlink leading to that section

nitpick: typo, it might be best to put a hyperlink leading to that section

YellowComet commented 2023年11月25日 17:00:11 +01:00

I don't know what the best approach would be here. We can go with either making Security a hyperlink or something like (Link to the security section) after "settings"

Typo fixed in 0655c94.

I don't know what the best approach would be here. We can go with either making `Security` a hyperlink or something like `(Link to the security section)` after "settings" Typo fixed in 0655c94.

n0toose commented 2023年11月22日 15:45:41 +01:00

"in SSH as well" -> "to secure your SSH key"

"in SSH as well" -> "to secure your SSH key"

YellowComet commented 2023年11月25日 17:00:37 +01:00

Done in 0655c94.

Done in 0655c94.

Copy link

Copy link