08.2023 rewrite

[meghan06]

See #62 , this PR is archived.

TODO List:

From TODO.txt

• Fix broken Jumper links in supported devices chart
• Update macOS Post-Install to include fixing NVRAM on 10th gen devices (DevirtualizeMimo)
• Organize guide by sections, i.e firmware pages go together in a group and whatnot
• Make some FAQ questions (the long ones) easier to comprehend
• Known Issues -> OS -> Linux add workaround for Broken USB-C on TigerLake and AlderLake
• Update Terminology page to include newer CPU generations
• Flashing Custom Firmware -> Step 2, include SuzyQ CCD as one of the possible methods
• Flashing Custom Firmware -> Updating coreboot, make instructions more instructionaly
• altOS -> Windows, specify that drivers are paid for SKL and newer only
• Add SOF/AVS sleep wake crash to known issues
• Update discounted CPUs in Windows and CSDriver page
• Note that PopOS and Debian 12 need custom kernel
• Post Install, add custom kernel reference (see Fix broken images introduced in the previous PR #12)

Others:

• there is a lot of jumping around and following links, this should really be more linear
• there is some unnecessary details in certain sections that can cause confusion, maybe these would be better if we made a section for a more detailed explanation
• certain processes like dev mode could be explained better
• change the order of steps and pages to be more linear (prerequisites, terminology, firmware explanation should go before any actual steps, then dev mode instructions next, then find system info, supported devices, flash fw, etc) the order will need more discussion
• move all WP instructions to a new page, then link to that in supported devices
• remove and reword certain sections/lines to be easier to understand all over the docs
• explain the steps of the firmware util a little better
• explain dev mode instructions mode, mention that you need to press ctrl + d every time you see os verification/dev mode screen
• move updating coreboot to a new page, the current page doesn't make sense
• give some tips for disassembling a device for people who haven't done it before
• move the linux compatibility spreadsheet to the docs (NEEDS WORK)
• explain keyd steps better (this really should be automated, I just need to figure out how to do that)
• not all terminology is relevant to everyone, move the terminology relevant to each page to the top and remove the terminology page
• create a page describing each platform/generation for OS/firmware support (linux support sheet could go here)

Other cool ideas:

• expand the ventoy page to be for general bootable drive creation
• explain that you should copy a code block exactly as is into the terminal (ctrl + shift + v is how you paste in a terminal)

[ninelore]

It should be mentioned too that the USB-C is not always broken has a chance to work ootb

[ninelore]

About Streamlining:

We really shouldn't turn documentation into a step-by-step guide.

Keep Pages for one topic each and maybe add a step-by-step guide as a seperate page.

In other words: Streamlining is bad because it will backfire on us

[meghan06]

It should be mentioned too that the USB-C is not always broken has a chance to work ootb

Alright.

We really shouldn't turn documentation into a step-by-step guide.

Some portions of the doc has to be step by step (i.e flashing firmware). If we keep pages for one topic each and maybe add a step-by-step guide as a seperate page, that'd be an insane amount of work and would probably require an entire rewrite.

[meghan06]

shut up spellbot. im deleting this thing.

[github-actions]

@check-spelling-bot Report

🔴 Please review

See the 📂 files view or the 📜action log for details.

Unrecognized words (2)

Entreprise
transitioning

To accept ✔️ these unrecognized words as correct, run the following commands

... in a clone of the [email protected]:meghan06/docs.git repository
on the main branch (ℹ️ how do I use this?):

curl -s -S -L 'https://raw.githubusercontent.com/check-spelling/check-spelling/main/apply.pl' |
perl - 'https://github.com/chrultrabook/docs/actions/runs/5982901230/attempts/1'

Available 📚 dictionaries could cover words not in the 📘 dictionary

Dictionary	Entries	Covers
cspell:cpp/src/cpp.txt	30216	1

Consider adding them using (in .github/workflows/spelling.yml):

      with:
        extra_dictionaries:
          cspell:cpp/src/cpp.txt

To stop checking additional dictionaries, add:

      with:
        check_extra_dictionaries: ''