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

Audit and fix a-simple-calculation.md page #38

Closed
21 of 25 tasks
minhhang107 opened this issue Nov 4, 2021 · 1 comment · Fixed by #74
Closed
21 of 25 tasks

Audit and fix a-simple-calculation.md page #38

minhhang107 opened this issue Nov 4, 2021 · 1 comment · Fixed by #74
Assignees

Comments

@minhhang107
Copy link
Contributor

minhhang107 commented Nov 4, 2021

I'd like to audit and fix the a-simple-calculation.md page based on tasks listed below.

Tasks:

  • Look for any typos
  • Make sure all Markdown is correctly done. The conversion was done automatically by a tool, so there may be more idiomatic ways to do some things
  • Check the page in a Desktop browser. Does it look OK? Are there any issues that need to be fixed?
  • Check the page in a Mobile browser. Does it look OK? Are there any issues that need to be fixed?
  • Try the page in both Light and Dark mode. Are there any issues that need to be fixed?
  • Try running the page through Lighthouse: https://developers.google.com/web/tools/lighthouse. Are there any issues that need to be fixed?
  • Try running the page through Web Hint: https://webhint.io/. Are there any issues that need to be fixed?
  • Tables that are really wide (types.md) could be converted to use SVG or flex/grid. Make wide visual tables fit in the available viewport. Another example is the table in docs/D-Modularity/pointers.md, where we should reduce the vertical padding/margins on tables. The tables are too large, and probably shouldn't be tables at all.
  • Prefer Markdown tables vs. raw HTML tags
  • Fix colours in tables so it uses global styles vs. inline styles
  • Use alt tags for all images. See https://supercooldesign.co.uk/blog/how-to-write-good-alt-text for suggestions
  • Avoid blockquote for indentation, and prefer q or blockquote only when actually quoting. Use Admonitions instead. Example: docs/D-Modulatirty/pointers.md: there are places where > Blockquote are being used and Admonitions could replace it. “Note:” Lightbulb info Admonition.
  • Make sure images work in dark and light modes. For example, docs/8-Computations/logic.md Flags image is white background, needs to work in dark. Create a “negative” or SVG so we can do Dark Mode? Can we programmatically create this negative?
  • Change colours for tables (don’t use Yellow). We should use the default colour theme.
  • Avoid using <b> and <i> to do emphasis.
  • Use backticks and all code for memory addresses and such in tables that use things like void, int, function names, memory addresses.
  • Make sure all code blocks use syntax highlighting
  • Centre images horizontally (esp. when they are small) so they work well at all responsive sizes
  • Check sub-script and super-script that they are correctly used in all cases
  • Consider including inter-site links to other pages that have related info
  • All links should have descriptive text for accessibility
  • Make sure that sub-headings (right-hand side) for each document are correct.
  • Improve readability of code comments (i.e., // and /.../) in dark mode (even light mode might need some work)
  • In places where ... was used as a fourth heading level, use #### instead.
  • Fix Frontmatter for page to include proper id, title, slug, etc.
@humphd
Copy link
Contributor

humphd commented Nov 4, 2021

Great, go for it!

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.

2 participants