selfcustody / krux

Open-source signing device firmware for Bitcoin
https://selfcustody.github.io/krux/
Other
175 stars 34 forks source link

release-24.07.0 docs changes only #413

Closed jdlcdl closed 2 months ago

jdlcdl commented 2 months ago

Description

These are just my thoughts on improvements to documentation, however when considering to merge these, please feel free to add commits, backing-out any of these changes, else ask me and I will adjust via more commits.

STILL TODO:

What is the purpose of this pull request?

codecov[bot] commented 2 months ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 94.64%. Comparing base (690357b) to head (af6d793).

Additional details and impacted files ```diff @@ Coverage Diff @@ ## release-24.07.0 #413 +/- ## ================================================ Coverage 94.64% 94.64% ================================================ Files 57 57 Lines 7073 7073 ================================================ Hits 6694 6694 Misses 379 379 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

odudex commented 2 months ago

Thank you Jean!

STILL TODO: many pages expect an anchor to explain adjusting the amigo screen be explained at /krux/faq/#troubleshooting-lcd-settings-on-maix-amigo however this section does not exist in the faq, this needs to be written or perhaps it already exists elsewhere?

I fixed many broken anchors created by the faq->troubleshooting migration, mkdocs caught most, but as links in "snippets" are absolute it just warns about being absolute, I can fix that.

/krux/getting-started/installing/from-test-release/ needs a section for manual install via ktool for the maixpy_cube

Will fix too

I noticed links to seedsigner.com and bitcoiner.guide at the bottom of krux/getting-started/usage/generating-a-mnemonic but I didn't notice one for coldcard (rethink external links?)

Should we add Coldcard or remove all?

When viewing docs via poetry run poe docs, the math expressions in /krux/getting-started/features/entropy are not nearly as pretty as they appear on github sites... confirm that this is expected, else to be fixed. (they're often wrapped in what looks like single or double dollar-signs.)

I believe math expressions will render in Github pages, but I'll look for tools to render it locally too.

This pr covers my review of all docs EXCEPT documentation related to setting up single-sig and multisig wallets in coordinators... but I will get around to reviewing that too.

Great, I'll go through your todo list while you review those

jdlcdl commented 2 months ago

I don't have an opinion on links to other sites, except that they might be consistent.

seedsigner has links in the SeedQR sections for understanding that format.

Since verification is important for everyone, we could have links to non-competing projects (like seedtool and iancoleman), otherwise if we're going to have links to some, we might as well link all of the signers that we mention. Self-custody bitcoin-nation is the next global empire, we're all on the same team!

odudex commented 2 months ago

Right, let's include it! We don't have any competing projects. Indeed, the greater the number of verification options, the better!

odudex commented 2 months ago

Thank you!