README: fixes, tweaks and re-organisation #73
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
When the README was written the `venv` tool was still quite new and not yet well established, so we choose to use the more conservative virtualenv tool. Time has passed and now `venv` is considered the best practice, so we should advice using it in our README. While at it also use `python3 -m pip` to call `pip`, because it is a good way to make 100% sure that the correct `pip` is called. Signed-off-by: Leonard Göhrs <[email protected]>
When the README was written the official product name and its capitalization was still somewhat in flux. Now we have an official format and it is "USB-SD-Mux". Consistently use it. Signed-off-by: Leonard Göhrs <[email protected]>
Signed-off-by: Leonard Göhrs <[email protected]>
Signed-off-by: Leonard Göhrs <[email protected]>
to satisfy corporate greed^w^w^w to help new users that discover the USB-SD-Mux via the GitHub page find more information about it and find ways to buy one. Signed-off-by: Leonard Göhrs <[email protected]>
These changes mostly come down to personal taste. Signed-off-by: Leonard Göhrs <[email protected]>
This allows us to modify the formatting of the README more freely in the future. Signed-off-by: Leonard Göhrs <[email protected]>
…tions This is intended to get new users up to speed quicker. For them knowing how the USB-SD-Mux works internally is certainly interesting (at least to me it is), but having a quick start guide on how to install the software and use it is even more important. This also re-structures the quickstart section so that the installation from different sources is part of it in the form of sub-sections. This integrates the "Distribution Packages" section better. I was also a bit confused that none of the installation methods cloned the git repository, so I've added one. The "Troubleshooting" section was moved to the bottom of the page, because that is where I would expect it to be. Signed-off-by: Leonard Göhrs <[email protected]>
1 task
jluebbe
reviewed
Apr 26, 2024
hnez
force-pushed
the
readme
branch
2 times, most recently
from
bd8e4de
to
b9c0635
Compare
The `pipx` command takes away some of the tedium of managing per-package Python virtual environments, but may not be available everywhere yet. So make `pipx` the number two option, after installation from the Linux distribution, but leave the other option of manually managing the `venv` in as well. Signed-off-by: Leonard Göhrs <[email protected]>
This point in the README should be one of the first where people start encountering issues, so leave a note about where to find first aid. Signed-off-by: Leonard Göhrs <[email protected]>
|
These changes look good to me. Thanks for taking the time to improve the README! Once the last thread is resolved this should be ready to merge. |
SmithChart
approved these changes
Apr 29, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Hi,
I've spent some time with the README recently and found a few things that I would like to see changed.
Since changes in prose like a README are always a bit subjective I am of curse open for discussion. Feel free to point out changes you do not like.