Improving the documentation structure

[gbishop]

Using the implementation to drive the documentation is getting confusing. I'm thinking about a better organization. The bold names below are Wiki pages. The other names are headings within the Wiki page. Actions is a page describing the Actions tab and all its content (what we have now). There is no separate page for Action, Conditions, or Updates. Those could be relegated to the Terminology page.

Methods will be described in one long page. If it get too long we'll break it up somehow. Likewise for Patterns.

What do you think?

• Actions

  • Action
    • Conditions
    • Updates

• Layout

  • Audio
  • Button
  • Customize
  • Display
  • Gap
  • Grid
    • Filter
  • Logger
  • Modal Dialog
  • Page
  • Radio
    • Option
  • Speech
  • Stack
  • Tab Control
    • Tab Panel
  • Visual Scene Display

• Content

  • Spreadsheet summary
  • Media

• Cues

  • Overlay
  • Fill
  • Circle
  • CSS

• Methods

  • Method
    • Timers
    • Handlers
      • Handler (Key, Pointer, Timer)
        • Conditions
        • Key Conditions
        • Responses
          • Activate
          • Next
          • Cue
          • Clear Cue
          • Start Timer
          • Emit
          • Log

• Patterns

  • Pattern
    • Group
    • Selector
      • Filter
      • Order by
      • Group by

[gbishop]

I have started work on this. The Patterns page is an example of what I intend.

[aetkie]

Re-visiting this discussion thread.

I see what you've proposed for the Patterns page and how each level corresponds to components in the OS-DPI. I made some changes to the page. I think there is still a need for the existing content that introduces Patterns and provides some explanation. I'll work on expanding on various levels that correspond to the OS-DPI (i.e. order by, group, etc).

[sofia-bg]

Quickly scanned through this page and this jumped out to me under How to Implement Patterns

2. If you want icons to be cued from left to right and top to bottom in order the buttons appear on the screen, use Row Column

3. If you want icons to be cued by column starting from left to right on the screen, use Column Row Scan rows then columns within the row. Cycle through the columns of a row 2 times before returning to row scanning.

   --> I am a little confused with how the row/column and column/row are explained. First I would revise to make the descriptions parallel. I might change syntax entirely to start with the name and then give the description. (i.e., Row/Column: cues... ). Second, my understanding is that it truly is scanning the whole row, not the individual icons. So in row column you are scanning each row from top to bottom and then when you select a row it scans left to right. Same with column/row that you scan each column from left to right and then once in a column from top to bottom.

   --> Cycle through the columns of a row 2 times before returning to row scanning. this sounds like a directive, but I think it is simply explaining the way that the cue in the image is programmed, presumably you do not have to have it cycle through 2 times, you could come up with any number you want. Thinking it could sound more like explaining what is there not implying that to work it must be set to 2 times.

5. If you want icons to be cued by control buttons (e.g., Home, Clear, Backspace, etc.) use Controls and Rows

--> I am not following what this means 

Also, I need a refresher, if you pick row/column or column/row is it scanning single cells at a time in those directions? forgot to deleted this after I went back to try out scanning in OS-DPI mid writing this post

[aetkie]

I appreciate your feedback and a second set of eyes on this. Making edits now.

One part of Patterns that is still confusing to me is how to make the cycling start. Which component in Patterns is where you determine the key that makes the scanning start cycling?

[aetkie]

I am looking at this design now grid_ex_1-3_scann.zip and I see how it scans row by row. It does scan continuously for me too, even though the cycle = 2.

My question is, how would we make the pattern do this:

1. Go row by row
2. Go back to Row 1 and scan icon by icon.

At first I thought this would be 2 different Patterns. But you can only have 1 active at a time. Does that mean a second Group within the active pattern? has anyone done this already?

[aetkie]

Figured it out! It's controlled in Methods. Under Switch, you would have 2 Key Handler boxes to differentiate the controls for row by row and then icon by icon.

[sofia-bg]

@aetkie can you share your new design? I am not quite understanding the pattern you are describing you were aiming for, it sounds like the already existing pattern so I would like to see it to understand.

[aetkie]

It does already exist. Hah. I figured it out.

This is what I am working on.
keyboard_predict_AE.osdpi.zip

Right now, it scans through row by row. And then you can go letter by letter.
The next thing I want to figure out is how to cycle through the Predictions row on the second sheet. But I haven't figured that out yet. Any advice?

[sofia-bg]

Not sure what you mean by on the second sheet - this might not be the exact order you want, but what I did was instead of grouping by rows, I made a new column called scan. Then I set it to order by component name. You would need to change the name of the components to whatever alphabetical order you want, but this way it does not group the predict with the first row of the keyboard. I assume this was happening because even though you don't state "row 1" in the predict sheet, it is still "row 1" for that component.
keyboard_predict_AE_SBG.zip

Also - to make my life easier I changed it so that it is right arrow to advance scans and space bar to select.

[gbishop]

Yes. It needs help for sure. I simply smashed the pages together. As (I think) you suggested earlier, I think it (as well as Methods and Cues) should start with examples that go from simple to complex. Grouping by rows seems simple and (I hope) pretty obvious. Likewise grouping by columns. Then we might point to another page that covers the Controls and Rows example. If we want to get really fancy we could include an example where the grouping and order is fully defined by the content from the spreadsheet.

…

On Tue, Jun 6, 2023 at 2:41 PM Andrea Etkie ***@***.***> wrote: Re-visiting this discussion thread. I see what you've proposed for the Patterns page and how each level corresponds to components in the OS-DPI. I made some changes to the page <https://github.com/UNC-Project-Open-AAC/OS-DPI/wiki/Patterns>. I think there is still a need for the existing content that introduces Patterns and provides some explanation. I'll work on expanding on various levels that correspond to the OS-DPI (i.e. order by, group, etc). — Reply to this email directly, view it on GitHub <#189 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABQK7F5ZK6KUNCXNR2GK3DXJ52VRANCNFSM6AAAAAAYGQPGKM> . You are receiving this because you authored the thread.Message ID: ***@***.*** com>

[sofia-bg]

@aetkie and maybe my advice is wrong above, maybe instead of calling it "choosing rows columns or columns rows" and explaining how these pre-made options run, maybe we need to explain how they are both programmed. For example Row column is only named that because that is what Gary wrote into the field for Name. And then it scans rows because #row is what is entered into the field Group By.

But can also appreciate maybe this is too complicated and we start with explaining they can choose either of the presets and how they work and then peel back to show why and how things can be changed to work differently?

@gbishop Does anything need to actually be entered into the name field next to group by? Currently you have Rows #row deleting doesn't change anything, but does this help for logging or something else?

[aetkie]

And then it scans rows because #row is what is entered into the field Group By.

That seems important to explain. I'll add that.

Pre-made options are intended to get people started. But with the understanding that the scanning patterns are endless...
I'll expand on this idea

[aetkie]

Patterns page updated. That's it for now. Will continue with further iterations as additional UIs (and my own understanding) progress.

[aetkie]

I think Sofia's working UI (when complete) will be a great example of scanning with controls and rows.

If we want to get really fancy we could include an example where
the grouping and order is fully defined by the content from the spreadsheet.

You would have to walk me through this a bit...

[gbishop]

Imagine you have an extra field (or 2 or 3) in your content. Then you can Group By or Order By those fields. So if I wanted to scan right to left for my Hebrew communication board I could make that happen with a (say) Order column in my content that counts down instead of up. Or I could create a spiral scan by having the order column count up in the order I wanted the buttons visited. Maybe you're doing a keyboard and want the most frequently used letters near the center of the screen and want to scan in concentric circles; just assign the appropriate number to each letter and then Order By that.

I'm not suggesting that any of those is a good idea. Just illustrating what could be done.

Does that help?

[sofia-bg]

@aetkie the current prototype I am working on does rely on the spreadsheet to define what data I want pulled in, and I have it pre-defined so I can play around with data in different areas of the UI (quadrants, halves, thirds, etc.) and doing it that way makes it so that I don't really have to change much in the OS-DPI except for which column in my spreadsheet I want to use to declare with data to fill in...

All that to say I am not actually using scanning in that design, its all point and dwell. But I am happy to think about ways to use the spreadsheet so you don't have to program as much on the OS-DPI side as we think about example we might want to make.

[aetkie]

@gbishop that makes sense. I can envision how that spreadsheet would be organized and reflected in the design.

[aetkie]

@sofia-bg I downloaded the spreadsheet for the design you're working on (block_to_direct). Maybe I can use the content you have to simulate different scanning patterns, other than row/column column/row. Let me poke around this week and see what I can come up wiht

[gbishop]

I'm pretty sure you could do it with the same controls by adding another group to the pattern. You'd move through the first group row by row (and if you selected a row, then button by button on that row) then when (if) you exhausted that group you'd move to the second group where you'd visit the items sequentially. I can't imagine why you'd want that behavior but I think you could get it.

…

On Thu, Jun 8, 2023 at 11:22 AM Andrea Etkie ***@***.***> wrote: Figured it out! It's controlled in Methods. Under Switch, you would have 2 Key Handler boxes to differentiate the controls for row by row and then icon by icon. — Reply to this email directly, view it on GitHub <#189 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABQK7FXMSKBZCFP32ZMI3LXKHU33ANCNFSM6AAAAAAYGQPGKM> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[sofia-bg]

@gbishop ah of course asking questions then looking. I couldn't figure out how to do filter yesterday because I was expecting the same sets of boxes to pop up that pop up when you add filter in the display tab. with only one box I wasn't sure what to do.

[sofia-bg]

Last comment for the morning, this is interesting to see the ways we attack problems differently that can make documentation hard. My go-to is to lean on the spreadsheet first and make new columns that I then can control whereas here Gary manipulated the OS-DPI without having to add anymore data.

[gbishop]

Why isn't this filter the same as the Grid filter? I'll have to think about that.

Also, I'd rather see you add to your spreadsheet than write complicated Patterns but I wanted to demonstrate the types of things you can do with Patterns.

[aetkie]

@sofia-bg I agree. There are many ways to solve the same problem. Like Gary, I want to make the OS-DPI do the work for me. My brain is almost never going back to the spreadsheet. But I'm glad yours does. Also these long discussion threads are very helpful for documentation.

[aetkie]

@gbishop your example patterns were extremely helpful. Thank you!

[sofia-bg]

When you add filter in layout:

When you add in patterns:

I just wasn't sure what to write in with only the one box.

[gbishop]

I understand. I'm wondering why I made them different? I'll have to try to figure out why past me did that.

…

On Fri, Jun 9, 2023 at 10:41 AM Sofia B-G ***@***.***> wrote: When you add filter in layout: [image: Screenshot 2023-06-09 at 10 39 32 AM] <https://user-images.githubusercontent.com/92817124/244725321-4b168751-2ba3-44fb-9fa7-6c3f2718dc6b.png> When you add in patterns: [image: Screenshot 2023-06-09 at 10 39 51 AM] <https://user-images.githubusercontent.com/92817124/244725472-2fbbdaa9-5c4d-4908-9170-de5cfbe10abf.png> I just wasn't sure what to write in with only the one box. — Reply to this email directly, view it on GitHub <#189 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABQK7FVNZXTVQNVQBXJHA3XKMY2FANCNFSM6AAAAAAYGQPGKM> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>