Add text to the README.TXT that is included in the .zip which the OpenACR editor now supports

GSA / openacr

OpenACR is a digital native Accessibility Conformance Report (ACR). The initial development is based on Section 508 requirements. The main goal is to be able to compare the accessibility claims of digital products and services. A structured, self-validated, machine-readable documentation will provide for this.

https://gsa.github.io/openacr/

Other

83 stars 18 forks source link

Add text to the README.TXT that is included in the .zip which the OpenACR editor now supports #273

Closed mgifford closed 2 years ago

mgifford commented 2 years ago

Firstly, wow on the .zip

But there is a blank README.TXT related to https://github.com/GSA/openacr-editor/pull/30

So what guidance do we want to include in the README.TXT file?

Users should know that they need to submit the YAML file & not the HTML document
People might need to to know how to open a .html file after they have exported the .zip file
People should be reminded not to edit the HTML file. That is just for viewing.
If people want to edit the OpenACR file they should be directed to https://gsa.github.io/openacr-editor/

What else?

danid123 commented 2 years ago

The only other thing I can think of is maybe phrasing things in terms of the people who would be sending or receiving the files:

If you need to gather feedback from other people in your organization, please send the zipped file (HTML and YAML) to your collaborators. Collaborators can view the report by opening the HTML file with any web browser. If they would like to make changes to the report, they should go to OpenACR Editor and upload the YAML file to make edits to the content of the report. Do not edit the HTML file directly, it is just for viewing the report.

If your report is final and you're ready to submit the report to an agency in response to an Request for Proposal (RFP), please attach the YAML file to your proposal.

I think the above captures all your bulletpoints?

bruce-usab commented 2 years ago

Sorry for not mentioning sooner -- .zip might be a problematic file extension for some agencies.

For example, as recently as year ago, FDMS.gov downloads were .z1p files -- with an email instruction to manually change the file extension after download! Yes, it is all ridiculous. But you know, security.

I have no idea if this still remains a common problem. Your GSA PM might have a better sense of that.

mgifford commented 2 years ago

I hate security theatre. Thanks for raising this though @bruce-usab

I think we'll be ok though. Hopefully .yaml files aren't also blocked. That would be a problem.

For folks who want the HTML version, but can't download the .zip file they can either save the page or just copy/paste the HTML output that is already output on the Report page.

Just checked and it works pretty well to just copy/paste into Word too. Not that this is a recommended approach.

@danid123 do you think we should add help text to explain this to people?

dmundra commented 2 years ago

Separate ticket to add help text to the button.

dmundra commented 2 years ago

@qjac location where we currently create an empty README.txt file to put in the .zip is https://github.com/GSA/openacr-editor/blob/main/src/components/report/ReportZipDownload.svelte#L27

Let me know if you have questions about the .zip setup. This is ready to go.

qjac commented 2 years ago

I submitted a PR ^ with very basic text formatting using the 2 paragraphs @danid123 wrote.

bruce-usab commented 2 years ago

I just had cause to download a zip file from Regulations.gov. The file they provide has an extension of .z1p, and instructions were provided to change the file extension.

This is just a datum. I have no real insight as to explanation for the current practice, but I am confident that it addressed an actual difficulty, for some large agency, at some point in time. The eRulemaking program is now managed by GSA, so that should help with communication on this.