Improve documentation

[krystian-hebel]

Affected component(s) or functionality (if applicable)

Documentation

Brief summary

Documentation currently doesn't reflect the state of the project. Many aspects are outdated, important things are omitted and technical details irrelevant to regular users are named in a way that suggests they are part of entry-level instructions (e.g. Running). Website has broken formatting, there is no clear division of responsibilities between website and documentation repository. In addition to that, some documentation is spread throughout other repositories, not always in the most fitting places.

Version

N/A

Additional context

Rough list of tasks to be done to improve the documentation, divided by source:

Website

• Reorder entries in the documentation to represent suggested order of reading.
• Split the documentation into more categories (currently have Documentation and Blueprints).
• Remove outdated and irrelevant to user entries:
  • CI
  • Jobs descriptions
  • GitlabCI configuration
  • Running (very misleading title...)
• Do a validity check of remaining pages:
  • Check links across the site (e.g. using https://github.com/lycheeverse/lychee)
    • Some links redirect to something else than expected (e.g. AMD APM) without returning an error. Setting max redirection number to 0 and manually checking links that do redirect may be inevitable.
  • Architecture
  • Contributing
  • Introduction to Late Launch
  • Use Cases
  • AMD GRUB
  • AMD LZ (renamed to SKL, outdated build options)
  • Measured Secure Boot
  • TXT GRUB
• Do a full rework:
  • Developers guide
  • Linux
  • FAQ
  • README in repo - add instructions for local preview
• Add:
  • Names created for and used by TrenchBoot to the glossary
  • Cross-links to publications mentioning TrenchBoot
    • UseCases.md: Add links to blogs, publications and a book TrenchBoot.github.io#43
    • Add missing publication cross-links TrenchBoot.github.io#44
  • User level documentation
    • Link to it on home page
    • Requirements
    • Linux installation guide
    • Qubes OS installation guide
  • Troubleshooting
  • High-level overview of all components and their interactions - blueprints?
  • SLRT - blueprints?
  • Xen (Qubes OS) - blueprints?
• Update events page.
• Do a spell/grammar/formatting check of all pages.
• Add precommit (or other mechanism) to check if new changes can break the formatting.

Documentation repository

• Deduplicate information available on website.
• Add HCL.
• Review, update and merge open pull requests.
• Roadmap - decide what to do with it (update? remove? change format?)
• Bump versions of documents in references.
  • Do we want to keep older revisions as well? Intel removed all references to TPM1.2 in later revisions, but it is still available in the wild.
• Check if QUICKSTART.md is still valid, update if not.
  • Recheck it again after all other tasks are completed, in case it gets updated in the meantime.
• Deduplicate presentations/README.md with website, save copy of presentations from linked events (if available).
• Move everything to the website, add deprecation note with link to website, archive the repo.

trenchboot-sdk

• Remove (or move elsewhere) instructions for building firmware for OptiPlex - it has nothing to do with this SDK.
• Add instructions for building Linux.
  • Update Dockerfile if needed.
• Add instructions for building for UEFI.
  • Update Dockerfile if needed.

Relevant documentation you've consulted

• https://trenchboot.org/ (https://github.com/TrenchBoot/TrenchBoot.github.io)
• https://github.com/TrenchBoot/documentation
• https://github.com/TrenchBoot/trenchboot-sdk

Related, non-duplicate issues

#8

[krystian-hebel]

I've started working on this in TrenchBoot/TrenchBoot.github.io#31, addressed points are marked in the first comment.

There are some pages I will need help with:

• https://trenchboot.org/blueprints/Linux_Late_Launch/ - @rossphilipson may know the most about current state, or whoever will work on our side on AMD implementation (@BeataZdunczyk CC) could try to do this based on changes sent to LKML. This could be a good way of getting to know the project.
• https://trenchboot.org/events/ - @dpsmith, @pietrushnic, @miczyg1 the list ends in 2020, surely there were presentations after that.
  • https://archive.fosdem.org/2021/schedule/event/firmware_suwd/
• https://github.com/TrenchBoot/documentation/blob/master/roadmap/Roadmap.pdf - honestly, no idea what to do with it, this format is impossible to update (not that I would know enough about future plans to update it in the first place).
• docs/meeting-minutes: Add notes from January TrenchBoot AEM meeting TrenchBoot.github.io#22 - very old minutes, could be finally merged.

[philipandag]

Update events page.

I have updated the events page with new events since 2020: TrenchBoot/TrenchBoot.github.io#32
There are 2 events/presentations where I have found some issues:

• "Secure Virtual Network Appliance with TrenchBoot" -- Embedded Linux Conference Europe 2019: There is only a short hand-recorded video of Piotr Król showing something on his laptop and a broken link to "description" which can be found in documentation repo. There does not seem to be any reference to this presentation on the Embedded Linux Conference Europe site
• "Trustworthy OE Devices and Software Supply Chain Integrity" -- Embedded Linux Conference Europe 2018: This again can be found in documentation repo and here we have only a poster and no reference of the presentation on Embedded Linux Conference Europe site

[philipandag]

Working on moving the [documentation repo] to the website here:
TrenchBoot/TrenchBoot.github.io#33

I think it is mostly done but there are still two very old open pull requests with last updated 2 and 4 years ago: https://github.com/TrenchBoot/documentation/pulls

Also I am not authorised to archive the documentation repository, so maybe someone else should do it. Forking and making PR only to add a deprecation note seems a bit excessive.

[miczyg1]

https://trenchboot.org/events/ - @dpsmith, @pietrushnic, @miczyg1 the list ends in 2020, surely there were presentations after that.

Naturally. It's just nobody updated with new presentations. Last time I edited the page I had t do some archeology to find slides and videos. Whoever is going to update it, will have to do the archeology again to find all presentations and materials.

[philipandag]

I think most of the missing events were added here TrenchBoot/TrenchBoot.github.io#32

[krystian-hebel]

TrenchBoot/TrenchBoot.github.io#42 has been merged, I've checked the items addressed by it.

[krystian-hebel]

Another set of changes merged with TrenchBoot/TrenchBoot.github.io#36, including README and cleanup of MkDocs plugins.

[krystian-hebel]

TrenchBoot/TrenchBoot.github.io#33 - Linux instructions and coreboot payload blueprint

TrenchBoot/TrenchBoot.github.io#43 - publications about TrenchBoot

[krystian-hebel]

TrenchBoot/TrenchBoot.github.io#37 - pre-commit added to CI, now adding wrongly formatted content should be harder, and we finally have green tick on the PR.

TrenchBoot/TrenchBoot.github.io#46 added Linux build instructions using trenchboot-sdk, which was updated to work with current debian:stable in TrenchBoot/trenchboot-sdk#12.