search

bitcoindevkit / bitcoindevkit.org

BDK project home page (originally magicalbitcoin.org 🧙)
https://bitcoindevkit.org/
49 stars 68 forks source link

Remove all tutorials from the website #168

Open thunderbiscuit opened 10 months ago

thunderbiscuit commented 10 months ago

This issue opens the discussion around removing the tutorials section of the website. Here are some of the reasons I think this is a good idea:

  1. Tutorials have mostly been a source of pain and confusion for new users. Their core flaw is that they do not age well. We've introduced breaking changes on most releases over the years (for good reasons! we're growing and fixing things!), and the upcoming 1.0 API basically obsoletes all tutorials altogether.
  2. The differences between the tutorials and the blog posts is that the blog posts are dated, and provide a specific opinion/view/insights into bdk at a specific point in time, rather than the promise of an evergreen walkthrough of how to perform a specific task.
  3. The tutorials are of varying quality, both in grammar and spelling, and maintaining them has proven to be work that no one on the core team is truly interested in picking up (I might be wrong on this; speak up if you disagree and would like to take the task on).

What should we do to provide tutorial-like instruction on bdk moving forward?

  1. One way we could keep some of the turtorials alive is by transforming them into blog posts (only the ones deemed interesting for archival purposes, or the ones where the author is interested in providing an updated version).
  2. Link to tutorials and blog posts on other websites (many developers have written extensively about bdk over the years and given example codebases, blog posts, etc. Those can be referenced in order to give them discoverability, while not taking on the burden of maintaining them.
  3. Love and care should be dedicated to a specific resource the team intends to maintain moving forward. I suggest the book-of-bdk for this. This is not intended to replace the tutorials, but should provide a starting point for developers intending to use bdk.
notmandatory commented 10 months ago

I agree that outdated tutorials are probably do more harm than help and the effort to maintain them is better spent building and maintaining book-of-bdk. If possible I'd like to have at least one minimal viable wallet "Hello World!" chapter for BDK 0.29 and/or 1.0.0 in the bdk book to send people to, and then create issues for migrating the rest. I'm also good with moving them back to be blog posts for now and migrate them to the book later.

ConorOkus commented 10 months ago

Thanks for raising. I agree with most of what you suggest here. Further, perhaps the focus of the bitcoindevkit.org website should be mostly educational/marketing material and help developers establish a good mental model. book-of-bdk is where you go for well-reviewed and tested walkthroughs.

We can probably convert all tutorials to blog posts for archival purposes in the interim while book-of-bdk is being built out and decide to remove them later.

MKDocs > Vuepress

reez commented 10 months ago

Also agree outdated tutorials can be more harm than good at times; for migration options I like what you laid out-

storopoli commented 10 months ago

Tutorials and documentation are always complicate to have it together. They have different user bases, use cases, discourse, and purposes.

I see some big-funded open source projects having them all together, but they have dedicated teams just to training materials (which is not our case).

I agree with the path moving forward and I think that we should promote book-of-bdk in the bitcoindevkit.org website.