search

jcsteh / osara

OSARA: Open Source Accessibility for the REAPER Application
GNU General Public License v2.0
127 stars 46 forks source link

Sprucing up the ReadMe #527

Open ScottChesworth opened 3 years ago

ScottChesworth commented 3 years ago

The next task on my to do list is to spruce up the ReadMe. There are just a few questions (well ok, five) I'd like to get clarification on before undertaking the grunt work.

  1. @jcsteh, do you mind if I soften language in a few spots to make the overall tone more welcoming/encouraging? For example, our current description of the Mac port would probably turn me off of trying it, whereas in reality, plenty of people are happily using it. I'll be mindful not to soften at the expense of accuracy.
  2. I'd like to remove some references to reaAccess that seem extraneous. It's true that we likely wouldn't be here without it, citing it in the intro makes sense, but I don't think it needs to be mentioned anywhere else nowadays.
  3. Any objections to me linking Ten Typical Tasks as an audio resource for getting started? I'd like to place it after the link to reaperaccessibility.com in "Additional Documentation". Feedback from the community has been both plentiful and universally positive.
  4. There are a ton of spots where capitalization has gone awry over time. I intend to batch fix these, but also wanted to float another change to how we're denoting assignments like Comma, Period and Dash. Right now, we use symbols. This forces users who don't have their screen reader set to all punctuation to examine character by character. Can I switch to writing those assignments in words as above for easier reading?
  5. Some actions that don't have specific assignments are listed, because reporting is either provided in context or they're part of custom actions we bundle. Some examples:
    • Track: Insert new track
    • Item: Remove items
    • Item: remove stretch marker at current position I'd like to group all of these actions in a new section with a short explanation that reporting is provided in context or as part of a bundled custom action. Essentially a better explained version of "these don't have specific keys, but you can still expect to be told about the results when they run". This seems like it'd be easier to understand for newbies.

Thoughts?

jcsteh commented 3 years ago 
1. @jcsteh, do you mind if I soften language in a few spots to make the overall tone more welcoming/encouraging? For example, our current description of the Mac port would probably turn me off of trying it

Heh, I was just looking at this earlier myself. That information is now not only unwelcoming, but quite incorrect. I don't consider the Mac build experimental any more, as much as I'd personally prefer I didn't have to deal with it ever again.

2. I'd like to remove some references to reaAccess that seem extraneous.

Agreed; I had the same thought. I think we can leave the bit about being inspired by it, but even the part about its current status is unnecessary now.

3. Any objections to me linking Ten Typical Tasks as an audio resource for getting started? I'd like to place it after the link to reaperaccessibility.com in "Additional Documentation".

Please do.

4. There are a ton of spots where capitalization has gone awry over time. I intend to batch fix these, but also wanted to float another change to how we're denoting assignments like Comma, Period and Dash.
   Right now, we use symbols. This forces users who don't have their screen reader set to all punctuation to examine character by character. Can I switch to writing those assignments in words as above for easier reading?

Aside from my general annoyance with the idea of compensating for user screen reader settings, I see two problems:

  1. This is going to be annoying for braille readers.
  2. The . symbol has several different names: full stop, period, dot. In choosing to write it out, we're biasing to one of those and that may confuse users.

I guess I can live with it if this is a really common cause for concern.

5. Some actions that don't have specific assignments are listed, because reporting is either provided in context or they're part of custom actions we bundle.
  I'd like to group all of these actions in a new section with a short explanation that reporting is provided in context or as part of a bundled custom action.

This seems reasonable. In ancient lore, when I started writing these lists, we didn't have a stable, bundled key map. Now that we do, there are more actions in those lists which are bound than not. Certainly, I agree what you're proposing is much friendlier now that it's feasible.

pitermach commented 3 years ago

On the topic of the Readme and Mac support, it's probably also worth mentioning that the Mac Osara is a universal binary so will work with both the Intel and ARM versions of Reaper, since the platform is still very new developers usually advertise this fact in their software descriptions so it's probably worth pointing out in Osara's case as well.

ScottChesworth commented 3 years ago
  1. This is going to be annoying for braille readers.

Fair point, I don't have a solution to that. It's a small proportion of our users so far as I can tell, but still.

  1. The . symbol has several different names: full stop, period, dot. In choosing to write it out, we're biasing to one of those and that may confuse users.

Our default maps are primarily tested on English US keyboard layout, so I'd go with US terminology. I guess I can live with it if this is a really common cause for concern.

I wouldn't say really common, but it has come my way a fair few times without prompting.

jcsteh commented 3 years ago

Re symbols as words: Ultimately, this isn't a battle I care enough about to win, so long as I have someone else to blame if someone doesn't like it. :)

ScottChesworth commented 3 years ago

Re symbols as words: Ultimately, this isn't a battle I care enough about to win, so long as I have someone else to blame if someone doesn't like it. :)

Hahaha, honesty! How about this? I'll do the initial batch of fixes with the existing format, preserve that version before I switch symbols to words. The key map doesn't change often, so there'll be a window of time where we can revert back to symbols easily if it causes an uproar.

ptorpey commented 3 years ago

Re symbols as words: Ultimately, this isn't a battle I care enough about to win, so long as I have someone else to blame if someone doesn't like it. :)

[PT] If you are looking for another opinion, I like the idea of spelling out the punctuations since, even though I use braille, I primarily listen to speech and don’t like switching back and forth between full punctuation and some punctuation or navigating by character to hear the punctuation. I wish I had kept documentation for my scripts etc. in that format over the years.

--Pete

ScottChesworth commented 3 years ago

I've gotten most (maybe all) of the text rewritten that I reckon needs softening or clarifying, and am a good way into batch fixing formatting issues here. But, I've run into trouble re question 5 (see first comment if you're coming in fresh). Moving contextual actions without specific keystrokes all into one section as proposed doesn't really resolve the situation if you're using the ReadMe to reference keystrokes, because you'd still be left in the dark about what keystrokes will run those actions. Would it not be clearer for users if I just keep them in place, note the keystroke that will run an action where relevant, and reference the custom action instead if a supported action is being used in that way? Examples:

jcsteh commented 3 years ago

Again, this was all started before OSARA had a bundled key map. So, I think what you're proposing is reasonable, but there's one caveat: we'd lose the information about the actions OSARA supports that are either unbound or included as part of custom actions. This wouldn't impact most users, but I imagine there are at least some users that might either bind some of these more basic actions themselves (e.g. Track: Insert new track), create entirely custom key maps or write other custom actions or scripts which depend on these more basic actions.

I think we could get around this by having two sections:

  1. The first would be for most users and would be mostly (maybe even entirely) about the stuff that is bound in the key map. That one would be as you propose; e.g. Custom: insert and name track: Control+T
  2. The second (maybe even an appendix closer to the bottom of the Usage section) would be the actions that OSARA supports which are either unbound or are included in custom actions.

Thoughts?

ScottChesworth commented 3 years ago

I think we could get around this by having two sections:

Solved, thanks. I'll do that. It's likely gonna be a couple days before I can get it finished, but think I have everything I need now.

tbdalgaard commented 3 years ago

Regarding question 4: Please keep symbols as symbols and not words. I have got a bit of questions of not native English speaking users who didn't know the English symbols and needed to reference these with their primary language. That is much easier if symbols are symbols instead of written out words.

Can't wait to watch the updated readme, man your ideas sound very intuitive.

ScottChesworth commented 3 years ago

not native English speaking users who didn't know the English symbols and needed to reference these with their primary language. That is much easier if symbols are symbols instead of written out words.

Thanks for letting me know. Symbols are staying then.

jcsteh commented 4 months ago

@ScottChesworth, do you still have plans here or should we close this?