search

kaspanet / rusty-kaspa

Kaspa full-node and related libraries in the Rust programming language. This is a stable version at the initial rollout phases.
ISC License
359 stars 109 forks source link

README improvements #321

Closed starkbamse closed 5 months ago

starkbamse commented 6 months ago

Changes

Why

tldr; I improved the readability of the readme.

Simplifying the documentation and making it more accessible is key for Kaspa adoption. When I first came to this repo a couple days ago, I was struck that such a cool network had such an unorganized repository. I believe that the proposed changes will simplify the process for new developers to get started.

These changes are obviously not perfect and I think there could be more information added regarding the WASM so that front-end developers that have little to no experience with complex languages like Rust to get engaged as well. :)

starkbamse commented 6 months ago

@aspect

CaffeinatedFunctionality commented 6 months ago

Love what you did here. Readmes have been super undervalued lately and aren't given a lot of love due to other developments.

starkbamse commented 6 months ago

Love what you did here. Readmes have been super undervalued lately and aren't given a lot of love due to other developments.

Thanks, I totally agree and feel like README's are one of the most important parts in a repo since they are the first impression of the project.

aspect commented 6 months ago

Apologies for delayed feedback.

This looks good, but I would like to request the following changes.

1) for now, let's remove the image from the top of the document. there is no consensus and the feedback for that specific image wasn't great. so we will think about it, but for now this should go.

2) Please refactor linux instructions to be presented as multi-line code. I think this can be done by adding back-slashes like so:

apt-get install clang-format clang-tidy \
clang-tools clang clangd libc++-dev \
libc++1 libc++abi-dev libc++abi1 \
...

The fact that this code now offers copy button is great, but the fact that you can not see the whole set of instructions on the screen and have to scroll for it is not good. So we need to make this fit on the screen.

3) I wanted to do this for a while, perhaps you can restructure the document to separate each platform section into <details> and <summary> so that each section becomes an openable section.

For example:

<details>
<summary>Installation on MacOS</summary>
... macos instructions
</details>

Then the other sections could perhaps be grouped this way as well. IMO this will significantly reduce the footprint of the README making it much cleaner.

For example, there can be a set of details sections for OS-specific installation + WASM + wRPC, then "Running the node" and "Mining" as well as "Simpa" can be in the open.

4) there need to be changes to include sudo in all appropriate linux-related commands as per https://github.com/kaspanet/rusty-kaspa/pull/341

starkbamse commented 5 months ago

@aspect

Good points! Refactored in accordance with your suggestions. Includes the edits made by @coderofstuff in #341, added as co-author. Therefore also closes #340

aspect commented 5 months ago

So now this looks the opposite side of the spectrum. There needs to be a balance of useful material presented and technical material being hidden. Here is the list of sections (in a specific order) that should be visible or hidden:

1) Remove TOC, there is no point of having TOC to a bunch of hidden sections. Hidden sections are a form of TOC. I think perhaps the TOC is what forced you to create headings to be able to link to this. If the document is structured properly with hidden sections, there is no need for TOC.

So that is roughly 3 top-level sections (3 H1 headings), where Installation and Benchmarking is closed (thus it looks like TOC), and the main focus is on Running the node, where instructions are open by default.

starkbamse commented 5 months ago

@aspect The documentation has been adjusted I have grouped everything and hidden everything except for how to run the node. I added an intro text that I wrote with the help of an LLM. Let me know your thoughts on it. I believe it can serve as a starting point.

starkbamse commented 5 months ago

Thank you for making this effort to cleanup this README.md

I have some minor requests before I can approve this.

Note: I've verified that the content here is a superset (but is mostly the same) as the old wiki.

Notable additions are the intro and the extra links to some terms (borsh, for example)

You are welcome, it is my pleasure to be a part of this and do my part in aiding the development of this interesting tech. Refactored in according to the issues you pointed out.