Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal: Human-readable format should not be a spreadsheet or table-style document #99

Open
jordansissel opened this issue Dec 3, 2024 · 6 comments · May be fixed by #113
Open

Proposal: Human-readable format should not be a spreadsheet or table-style document #99

jordansissel opened this issue Dec 3, 2024 · 6 comments · May be fixed by #113

Comments

@jordansissel
Copy link

As the title suggests, I propose that the human readable format for this baseline stuff should be something not a table or spreadsheet. The long-form text of exposition and explanation should not be typeset into a skinny spreadsheet-like structure. For a visual example, this project's current website looks like this on my phone:

image

Too much whitespace is dedicated to the data columns with the least amount of text. Even when I scroll across, the table permits at most 3 words per line. It's not great ;) Yes, it looks different on my computer with a bigger screen and different layout provided by the browser on this table.

The longer "criteria details" area below the table feels informative enough without needing the table above it.

Thoughts?

@funnelfiasco
Copy link
Contributor

The current styling of the webpage was not designed with mobile browsing in mind (and it wasn't even checked on a mobile browser), but that doesn't mean it can't be. If the small-window view gave the last column more space, would that be sufficient to address your concerns?

If not, do you have any suggestions for an alternative presentation? We want the table (or whatever replaces it) to be relatively dense, so that people can get a quick understanding of the criteria and then click through to the one they want more details on.

What about something like this?

OSPS-EX-01  1  Example
     Examples MUST NOT use lorem ipsum because Latin gibberish is still gibberish.
OSPS-EX-02  1  Example
     Examples must use domain names reserved for that purpose as described in section 6.5 of RFC 6761

@SecurityCRob
Copy link
Contributor

I agree with the visibility/usability checking we need to do prior to going live. The spreadsheet/table-style of organization has its place within our collateral, but probably shouldn't be the main person-readable method. A next step we have is once the control mappings are agreed upon, we feed that info back into the yaml file. We've briefly chatted about "the spreadsheet" and how that data can be presented. I certainly have no desire to try and build the table again in markdown and the info can't exist in a gsheet forever. I'd love to hear some conversation on how we might display the control-mapping information more clearly and simply.

@david-a-wheeler
Copy link
Contributor

I think what you want is a "responsive table" - that is, the formatting radically changes when you have a narrow screen so it's still readable by breaking it differently. Unsuprisingly, there are many ways to do this. A few links:
https://css-tricks.com/responsive-data-table-roundup/
https://codepen.io/shellbryson/post/responsive-tables
https://github.com/rootwork/responsive-tables-builder (links to some options)

We should look at options, and then apply it.

@eddie-knight
Copy link
Contributor

@SecurityCRob we do have spots in the current template (and yaml) for control mappings!

@funnelfiasco
Copy link
Contributor

Of the things we've discussed so far, I think trying a responsive table approach (in addition to being as terse as possible with the criteria) is the best approach. We can do it now or I can do it later this week as part of the more general web-rearrangement I want to do.

@funnelfiasco
Copy link
Contributor

I've been experimenting with a <div> based approach that almost, but doesn't quite work. But I think I've stumbled upon a better option. I should have some time on Monday to clean up my mess and share it with the group.

@funnelfiasco funnelfiasco linked a pull request Dec 17, 2024 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants