suborbital / docs

Documentation monorepo for Suborbital projects and products
https://docs.suborbital.dev
Apache License 2.0
8 stars 5 forks source link

Big Compute docs clarification blitz #155

Closed LauraLangdon closed 2 years ago

LauraLangdon commented 2 years ago

WIP update to SCN docs, more details to come

Edit: this is now semi-complete, with more updates planned for the pages on namespaces, configuring storage for cloud deployment, FQFN, custom templates, and custom libraries.

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

flaki commented 2 years ago

Preview branch deploy for this PR: https://suborbital.github.io/docs/laura/update-scn-docs/ (it's always https://suborbital.github.io/docs/ + the branch name + / )

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

github-actions[bot] commented 2 years ago

10 total issues, 1 error, and 9 warnings found for docs.suborbital.dev

Details

ERROR WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail ```html Search ``` This element has insufficient contrast at this conformance level. Expected a contrast ratio of at least 4.5:1, but text in this element has a contrast ratio of 2.27:1. Recommendation: change text colour to #000610. ---
WARNING WCAG2AA.Principle1.Guideline1_3.1_3_1.H48 ```html

📝 docs | :octocat: repo | 🙋🏽‍♀️ issues | 🏪 marketplace | A11yWatch

ospencer commented 2 years ago

@callahad after this is merged I plan to do https://github.com/suborbital/docs/issues/162 to ensure we've got consistent formatting.

LauraLangdon commented 2 years ago

Re: https://github.com/suborbital/docs/pull/155#pullrequestreview-1074226752 from @callahad:

The website/docs/assets/editor-screen.png image still seems huge (over 300k!)... I think we should crop it further, reduce its resolution, and send it through a compressor.

I'm concerned that if it's smaller or lower res it'll be impossible to read. If it doesn't need to be easy to read, I could just remove it instead! I'll create an issue to track this so we can discuss it when you get back: https://github.com/suborbital/docs/issues/165

  • It seems like many of the prose changes switch from one sentence per line to hard-wrapping at ~80 characters. Others do not hard wrap. Others seem to break lines at arbitrary locations. Do we care if this is consistent?

I think this will be addressed by https://github.com/suborbital/docs/issues/162, but I'll also spend some more time trying to find that setting in my IDE.

flaki commented 2 years ago

@callahad @LauraLangdon I've re-created the screenshot and re-compressed it with OxiPNG (using Squoosh): functioneditor-oxi

It should be roughly ~66KB now, it is a 934x525px@2x image (for retina screens), 934px is the maximum extent of the content column of the docs. Part of the reason the original was so large it seems is that it was converted from a lossy JPEG to a lossless PNG so the artifacts were giving a hard time to the compressor.

callahad commented 2 years ago

Here it is at 28 KB:

editor-screenshot

LauraLangdon commented 2 years ago

@callahad @LauraLangdon I've re-created the screenshot and re-compressed it with OxiPNG (using Squoosh): functioneditor-oxi

It should be roughly ~66KB now, it is a 934x525px@2x image (for retina screens), 934px is the maximum extent of the content column of the docs. Part of the reason the original was so large it seems is that it was converted from a lossy JPEG to a lossless PNG so the artifacts were giving a hard time to the compressor.

Thanks, Flaki!

LauraLangdon commented 2 years ago

Here it is at 28 KB:

editor-screenshot

Thanks, Dan!