[meta] Audit and Fix all Markdown Pages

[humphd]

This is a meta issue, meant to organize the work necessary to audit and fix all existing markdown pages in docs/. If you want to work on this, the first step is to file a new issue for a given page and then leave a comment here with a link to the issue and name of the file you're working on.

Introduction

The IPC C notes are written in 30 Markdown files. These files have been automatically translated to Markdown:

A-Introduction

• compilers.md ✅ Audit and Fix Compilers.md #43 @hphan9
• computers.md ✅ Audit and Fix computers.md #45 @joshuali7536
• information.md ✅ Audit & fix Information.md page  #44 @Yoda-Canada

B-Computations

• a-simple-calculation.md ✅ Audit and fix a-simple-calculation.md page #38 @minhhang107
• expressions.md ✅ Audit and fix expressions.md Page #39 @gusmccallum
• logic.md ✅ Audit and Fix logic.md #52 @Reza9472
• style-guidelines.md ✅ Audit and Fix style-guidelines.md #49 @roman-rezinkin
• testing-and-debugging.md ✅ Audit and fix testing-and-debugging.md #86 @abatomunkuev
• types.md ✅ Audit and fix types.md #90 @lmpham1

C-Data-Structures

• arrays.md ✅ Audit and Fix arrays.md #40 @lyu4321
• structures.md ✅ Audit and fix structures.md page #51 @dbelokon

D-Modularity

• functions-arrays-and-structs.md ✅ Audit and fix functions-arrays-and-structs.md #79 @dhillonks
• functions.md ✅ auditing markdown file "functions.md" #26 @AndreWillomitzer
• input-functions.md ✅ Audit and Fix input-functions.md #33 @a-rokay
• library-functions.md ✅ Audit and fix library-functions.md #105 @japneetsingh035
• output-functions.md ✅ Audit and fix output-functions.md  #87 @MizuhoOkimoto
• pointers.md ✅ Audit and fix pointers.md page #36 @JerryHue

E-Secondary-Storage

• records-and-files.md ✅ Audit and fix records-and-files.md #85 @JiaHua-Zou
• text-files.md Audit and fix E-Secondary-Storage/text-files.md #122

F-Refinements

• algorithms.md ✅ Audit & fix algorithms.md page #28 @oliver-pham
• character-strings.md ✅ Audit and fix character-strings.md #99 @tpmai22
• more-input-and-output.md ✅ Audit and fix more-input-and-output.md #82 @rclee91
• pointers-arrays-and-structs.md ✅ Audit and fix pointers-arrays-and-structs.md #89 @Antonio-Bennett
• portability.md ✅ Audit and fix portability.md #94 @tcvan0707
• string-library.md ✅ Audit and fix string-library.md page #29 @hlavu
• two-dimensional-arrays.md ✅ Audit and Fix two-dimensional-arrays.md #88 @DerekJxy

Resources-Appendices

• ascii-collating-sequence.md ✅ ASCII Collating Sequence image converted into Table #80 @aserputov
• data-conversions.md Audit and fix Resource-Appendecies/data-conversions.md  #123
• ebcdic-collating-sequence.md ✅ converted EBCDIC collating sequence image into table #77 @mkim219
• operators.md ✅ Audit and Fix operators.md #42 @GMOTGIT

Check List

When working on one of these pages, here are some things to consider

• 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.

Filing Issues

If you notice issues that you can't, or don't want to fix, please file separate issues.

[humphd]

To any OSD600/DPS909 students looking to get involved, this is a great issue to join. Let me know if you want to help out, and I'll assign you one of the pages.

[AndreWillomitzer]

Hi sir I want to work on this but the checklist is a little overwhelming. These are just suggestions of what to look for right? For example we could go down the list, and if we find 3 or 4 to fix and they're smaller issues we could maybe let others handle some issues on the same page?

I am familiar with the C notes themselves since I tutored the class if that helps at all.

[humphd]

@AndreWillomitzer correct, these are the types of things we want to look at in the various files. Why don't you take one, and try looking for things, and see what you find. If there are 50 issues that have to be fixed, you could fix some, and file issues for others to fix in additional PRs. This will be a team sport!

It's awesome that you know the C notes so well, that will be a huge help. Thanks for diving in to help. Let me know which file you'll do, and file an issue to get started.

[AndreWillomitzer]

Hmmmm I think I will do "functions.md" but I'll have a look as well.

[AndreWillomitzer]

Unless you have a suggestion of a page where you know there are a few things I will have to fix.

[humphd]

@AndreWillomitzer functions.md sounds good. Go ahead and file an issue for this, (you can copy/paste the text at the top of this, but limit it to that single file). I'll assign you.

[AndreWillomitzer]

@humphd Hi sir I filed the issue. Which checks do you think would be the best to start with/most likely to have issues in the pages? I was thinking alt tags would be one.

[humphd]

@AndreWillomitzer just start working through and check as many as you can. Every page is different in terms of what it needs. Part of what you're doing at first is identifying the scope of the work.

[AndreWillomitzer]

@humphd Not sure if what I found is really an issue or not, I notice on the pages some code is colored some is not. The huge blocks have syntax highlighting, but the single inline codes don't.

[humphd]

That's normal. You can't specify a syntax for single backtick inline blocks. Only the three-backtick ones have a syntax type.

[a-rokay]

I can work on input-functions.md, issue.

[joshuali7536]

Hi I can work on computers.md, seen in issue #45

[roman-rezinkin]

Hi, I can work on style-guidelines.md, as seen in #49

[dbelokon]

Hello!! Can I please work on structures.md page? #51 😁

[dhillonks]

Can I work on functions-arrays-and-structs.md? #79

[RC-Lee]

Hi, can I work on more-input-and-output.md #82 . Thanks!

[JiaHua-Zou]

can I work on records-and-files.md mention on #85.

[abatomunkuev]

Hello! I would like to work on testing-and-debugging.md, that is mentioned in issue #86

[MizuhoOkimoto]

Hi! I would like to work on output-functions.md. I filed the issue in #87

[DerekJxy]

Hi! I would like to work on two-dimensional-arrays.md. As I mentioned in issue #88 .

[lmpham1]

Hello @humphd, I'd like to work on type.md.
Issue link: https://github.com/Seneca-ICTOER/IPC144/issues/90

[tcvan0707]

Hello @humphd, I would like to work on portability.md
Here is my issue: #94

[tpmai22]

I can work on character-strings.md see #99 @humphd

[japneetsingh035]

Did someone work on library-functions.md? if available, please let me know @humphd. Thank you!

[humphd]

@japneetsingh035, go for it, it's all yours.

[humphd]

At this stage, every document has been finished, started, or an issue is filed separately. Nice work everyone. Please follow-up in new issues. Closing.