docs: Rewrite README to make it more appealing #28174

aureleoules commented at 9:28 PM on July 27, 2023: member

The current README is pretty bland and I believe it could need a few improvements to enhance its value and appeal.

This pull request updates the README to make it more appealing. The changes are the following:

Adding emojis 🚀 which makes the document more vibrant
Use a more casual and interactive language to engage the reader

All the original technical contents were preserved, and the structure of the document remains the same to ensure that users still find the information they're accustomed to.

These changes aim not only to keep the document detailed and informative but also to make it easy-to-read and engaging, especially to users who may be new to the Bitcoin Core project and attract new contributors.

See preview: https://github.com/aureleoules/bitcoin/blob/2023-07-update-readme/README.md.

DrahtBot commented at 9:28 PM on July 27, 2023: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Reviews

See the guideline for information on the review process.

Type	Reviewers
Concept NACK	stickies-v

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

DrahtBot added the label Docs on Jul 27, 2023

in README.md:25 in 16591977d9 outdated

  31 |  -------------------
  32 |  
  33 | -The `master` branch is regularly built (see `doc/build-*.md` for instructions) and tested, but it is not guaranteed to be
  34 | -completely stable. [Tags](https://github.com/bitcoin/bitcoin/tags) are created
  35 | -regularly from release branches to indicate new official, stable release versions of Bitcoin Core.
  36 | +Our `master` branch is constantly evolving with regular builds (see `doc/build-*.md` for instructions) and tests, although it might not always be stable. Official stable release versions are marked with [tags](https://github.com/bitcoin/bitcoin/tags).

jonatack commented at 9:41 PM on July 27, 2023:

Not sure, but "regular builds" may not be interpreted the same as "regularly built"

in README.md:27 in 16591977d9 outdated

  37 |  
  38 | -The https://github.com/bitcoin-core/gui repository is used exclusively for the
  39 | -development of the GUI. Its master branch is identical in all monotree
  40 | -repositories. Release branches and tags do not exist, so please do not fork
  41 | -that repository unless it is for development reasons.
  42 | +We use https://github.com/bitcoin-core/gui repository solely for GUI development. Its master branch serves as a clone in all monotree repositories. We do not have release branches and tags here, so it is recommended to fork this repository only for development purposes.

jonatack commented at 9:45 PM on July 27, 2023:

We use the https://github.com/bitcoin-core/gui repository solely for GUI development. Its master branch serves as a clone in all monotree repositories. It doesn't have release branches and tags, so you only need to fork it for development purposes.

or s/We use/We use the/, s/tags here/tags there/ and s/fork this/fork that/

in README.md:35 in 16591977d9 outdated

  52 | -Testing and code review is the bottleneck for development; we get more pull
  53 | -requests than we can review and test on short notice. Please be patient and help out by testing
  54 | -other people's pull requests, and remember this is a security-critical project where any mistake might cost people
  55 | -lots of money.
  56 | +Testing and code review is vital for our project’s health; we receive more pull requests than we can review and test quickly. Please understand the delay and assist by testing others' pull requests.  
  57 | +This is a security-critical project, where any small mistake can cost heavily.

jonatack commented at 9:45 PM on July 27, 2023:

Use newlines consistently.

in README.md:34 in 16591977d9 outdated

  51 |  
  52 | -Testing and code review is the bottleneck for development; we get more pull
  53 | -requests than we can review and test on short notice. Please be patient and help out by testing
  54 | -other people's pull requests, and remember this is a security-critical project where any mistake might cost people
  55 | -lots of money.
  56 | +Testing and code review is vital for our project’s health; we receive more pull requests than we can review and test quickly. Please understand the delay and assist by testing others' pull requests.

jonatack commented at 9:53 PM on July 27, 2023:

I like "Please be patient and help out by reviewing and testing" better than "Please understand the delay (sounds like an airline announcement :) and assist (other passengers after donning your own life vest first ;) testing". Avoid sounding too corporate.

The bottleneck aspect might be helpful to keep.

jonatack commented at 10:28 PM on July 27, 2023:

FWIW it looks like this section dates back to 2012 or earlier!

Testing and code review is the bottleneck for development; we get more
pull requests than we can review and test. Please be patient and help
out, and remember this is a security-critical project where any
mistake might cost people lots of money.

in README.md:53 in 16591977d9 outdated

  77 |  
  78 | -Changes should be tested by somebody other than the developer who wrote the
  79 | -code. This is especially important for large or high-risk changes. It is useful
  80 | -to add a test plan to the pull request description if testing the changes is
  81 | -not straightforward.
  82 | +A crucial part of development is that changes should be tested by someone other than the code's author. This is highly significant for substantial or high-risk modifications. It helps if a test plan is added to the pull request if testing the changes isn't straightforward.

jonatack commented at 9:55 PM on July 27, 2023:

I'm not sure this paragraph is an improvement; it seems a little less easy to read and more verbose.

in README.md:58 in 16591977d9 outdated

  85 | +Translations 🌎
  86 |  ------------
  87 |  
  88 | -Changes to translations as well as new translations can be submitted to
  89 | -[Bitcoin Core's Transifex page](https://www.transifex.com/bitcoin/bitcoin/).
  90 | +For any changes to translations or new translations, simply go to the [Bitcoin Core's Transifex page](https://www.transifex.com/bitcoin/bitcoin/).

jonatack commented at 9:55 PM on July 27, 2023:

Not sure this is clearer.

in README.md:29 in 16591977d9 outdated

  41 | -that repository unless it is for development reasons.
  42 | +We use https://github.com/bitcoin-core/gui repository solely for GUI development. Its master branch serves as a clone in all monotree repositories. We do not have release branches and tags here, so it is recommended to fork this repository only for development purposes.
  43 |  
  44 | -The contribution workflow is described in [CONTRIBUTING.md](CONTRIBUTING.md)
  45 | -and useful hints for developers can be found in [doc/developer-notes.md](doc/developer-notes.md).
  46 | +Find out all about how to contribute, and other useful tips for developers, [here](CONTRIBUTING.md) and [here](doc/developer-notes.md).

jonatack commented at 10:00 PM on July 27, 2023:

Could also mention the productivity notes in doc/. I like the original paragraph better, however, in part as the linked docs don't really contain "all" about how to contribute.

jonatack commented at 10:03 PM on July 27, 2023: member

A few suggestions.

(I'm not sure who the emojis and "We" narration would be more appealing to and which target audience is being aimed for, but no strong opinion. Sugarcoating things might be a little akin to false advertising, though 😄.)

jonatack commented at 10:07 PM on July 27, 2023: member

Suggest running test/lint/lint-whitespace.py on this change to appease the lint CI.

docs: Rewrite README to make it more appealing d18998dfd1

aureleoules force-pushed on Jul 27, 2023

DrahtBot added the label CI failed on Jul 27, 2023

aureleoules commented at 10:18 PM on July 27, 2023: member

Thanks @jonatack, I addressed your suggestions and rolled back some of my changes.

in README.md:14 in d18998dfd1

  15 | -validate blocks and transactions. It also includes a wallet and graphical user
  16 | -interface, which can be optionally built.
  17 | +Bitcoin Core is your gateway to the Bitcoin network. It downloads and validates transactions and blocks in real-time! It also includes a wallet and graphical user interface (GUI) which can optionally be built.
  18 |  
  19 | -Further information about Bitcoin Core is available in the [doc folder](/doc).
  20 | +Curious to know more? Find further details in [doc folder](/doc)

jonatack commented at 10:37 PM on July 27, 2023:

Curious to know more? Find further details in [doc folder](/doc).

in README.md:27 in d18998dfd1

  37 |  
  38 | -The https://github.com/bitcoin-core/gui repository is used exclusively for the
  39 | -development of the GUI. Its master branch is identical in all monotree
  40 | -repositories. Release branches and tags do not exist, so please do not fork
  41 | -that repository unless it is for development reasons.
  42 | +We use the https://github.com/bitcoin-core/gui repository solely for GUI development. Its master branch serves as a clone in all monotree repositories. It doesn't have release branches and tags there, so you only need to fork it for development purposes.

jonatack commented at 10:38 PM on July 27, 2023:

We use the https://github.com/bitcoin-core/gui repository solely for GUI development. Its master branch serves as a clone in all monotree repositories. It doesn't have release branches and tags, so it's only useful to fork it for development purposes.

or just s/tags there,/tags,/

in README.md:70 in d18998dfd1

  66 | @@ -74,5 +67,4 @@ Changes to translations as well as new translations can be submitted to
  67 |  Translations are periodically pulled from Transifex and merged into the git repository. See the
  68 |  [translation process](doc/translation_process.md) for details on how this works.
  69 |  
  70 | -**Important**: We do not accept translation changes as GitHub pull requests because the next
  71 | -pull from Transifex would automatically overwrite them again.
  72 | +**Important**: Please note, we do not accept changes to translations as GitHub pull requests, as the next Transifex pull would overwrite them.

jonatack commented at 10:40 PM on July 27, 2023:

Suggest dropping either "Important:" or "Please note," -- both seem to be too much.

jonatack commented at 10:42 PM on July 27, 2023: member

A few more suggestions.

Just one opinion: in dark mode, which I use exclusively, I find the emojis are large, bright, and highly distracting from the text. If others agree, maybe remove them or make them smaller (not sure that's possible with markdown) or use fewer of them.

DrahtBot removed the label CI failed on Jul 28, 2023

russeree commented at 2:19 AM on July 28, 2023: contributor

My technical objection is that emoji illustrations vary between browsers, devices, and browser versions. The use of emojis would create an inconsistent experience between platforms.

My emotional and personal objection is and I mean this in the nicest way possible. I don't like the 'vibe' the changes to more informal language creates. It also makes the document less concise.

The phrase Curious to know more? Find further details feels like a pitch almost as compared to the current Further information about Bitcoin Core is available
Use of an exclamation point in It downloads and validates transactions and blocks in real-time! feels forced and again like a pitch. Don't get me wrong I love me some freshie blocks and TXs but...
Emojis make this feel like an AI model or application repo see https://github.com/Significant-Gravitas/Auto-GPT my preference is to have very concise unbiased language and visuals. Visuals should also not induce bias. This could be construed as good or bad.

ariard commented at 2:49 AM on July 28, 2023: member

I’m not sure keeping the project documentation as easy-to-read and engaging with emojis is that much a goal in itself considering Bitcoin Core is a security-first project underpinning a $567 billions ecosystem, where contributors would be rather invited to run their workflow on attack-surface minimized workstation. Rich graphical rendering requires lengthier and more opaque software supply chain.

Not a strong opinion, though there has been a talk at DEFCON 30 on how emojis can be used to craft shellcode :)

in README.md:12 in d18998dfd1

  12 |  ---------------------
  13 |  
  14 | -Bitcoin Core connects to the Bitcoin peer-to-peer network to download and fully
  15 | -validate blocks and transactions. It also includes a wallet and graphical user
  16 | -interface, which can be optionally built.
  17 | +Bitcoin Core is your gateway to the Bitcoin network. It downloads and validates transactions and blocks in real-time! It also includes a wallet and graphical user interface (GUI) which can optionally be built.

stickies-v commented at 11:10 AM on July 28, 2023:

I don't like this current rewording, but I think I agree with your intent of adding some more information of what the Bitcoin Core project stands for and who we target, e.g. highly reviewed, robust and stable code, highly performant one-stop-shop for running a node and wallet to fully interface with the Bitcoin Network, ...

stickies-v commented at 11:10 AM on July 28, 2023: contributor

NACK.

I think documentation needs to be as concise and simple as possible, but I feel like the current version does a good job at that already. The current language is factual and not more formal than it needs to be.

In a world of overmarketed crypto projects, I think maintaining sober documentation is a nice differentiation.

aureleoules commented at 11:31 AM on July 28, 2023: member

I understand the points you have raised and do somewhat agree with them. Closing this PR.

aureleoules closed this on Jul 28, 2023

bitcoin locked this on Jul 27, 2024