New project idea: miners community area on bitcoin.org?

[Mike Hearn]

It's become apparent that we have a major problem with transmission of cultural knowledge around mining. Many miners seem to not properly understand what mining is for, how it works or how to properly mine in a decentralised manner.

One obvious potential cause for this problem is there's nowhere "official" that people can learn what they should do.

I'm wondering if it makes sense to have a spinoff project, or find new people, who can help build a miner sub-site on bitcoin.org that:

• Explains the basics of mining and in particular why running Bitcoin Core is critical to decentralisation
• How to set up p2pool or getblocktemplate based mining where the pool doesn't control tx selection
• Perhaps a newbie oriented help forums? bitcointalk, other than being a noisy trollfest, is for general discussion and not explicitly helping people get set up.

What do you guys think?

[Saïvann Carignan]

This could perhaps be part of the "Run a Full Node" page:
https://github.com/bitcoin/bitcoin.org/issues/410

All in all, I think it's generally a good idea. Although to be very
honest, by reading all comments on this issue, my impression is that
most miners today only care about short-term profit.

So, to me, the most efficient way to tackle the problem would require
decentralized mining to be as profitable and simple to run than any form
of centralized mining.

So, basically imagine you could bundle p2pool / bfgminer / Bitcoin Core
together and you just present a simple "Mine" button to the user.

Only by then, you'd provide a better user experience. But still, Bitcoin
Core would need to use some UOT trick by then to drastically reduce
initial synchronization time. And P2Pool would need to actually scale
without compromising profits for small miners.

Not to mention that payout variance would still be an issue, and moving
miners from big pools to fix this problem could remain a big challenge
without serious pressure from the community. Sadly, I wouldn't be
surprised that one year from now, people will already be used to
centralized pools unless something serious happens to them (legal risks,
attacks, corruption, etc).

However, I do believe we can increase the number of full nodes with the
Developer Documentation, because we're providing useful examples that
will answer real needs, so users might create solutions running full
nodes on reliable servers for a reason other than charity.

Saïvann

Le 2014-06-13 14:33, Mike Hearn a écrit :
> It's become apparent that we have a major problem with transmission of
> cultural knowledge around mining. Many miners seem to not properly
> understand what mining is for, how it works or how to properly mine in a
> decentralised manner.
>
> One obvious potential cause for this problem is there's nowhere
> "official" that people can learn what they should do.
>
> I'm wondering if it makes sense to have a spinoff project, or find new
> people, who can help build a miner sub-site on bitcoin.org

> <http://bitcoin.org> that:
>
> * Explains the basics of mining and in particular *why running Bitcoin
> Core is critical to decentralisation*
> * How to set up p2pool or getblocktemplate based mining where the pool

> doesn't control tx selection

> * Perhaps a newbie oriented help forums? bitcointalk, other than being

> a noisy trollfest, is for general discussion and not explicitly
> helping people get set up.
>
> What do you guys think?
>

> --
> You received this message because you are subscribed to the Google
> Groups "bitcoin-documentation" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to bitcoin-document...@googlegroups.com
> <mailto:bitcoin-document...@googlegroups.com>.
> For more options, visit https://groups.google.com/d/optout.

[David A. Harding]

On Fri, Jun 13, 2014 at 08:33:33PM +0200, Mike Hearn wrote:
> Many miners seem to not properly understand what mining is for, how it

> works or how to properly mine in a decentralised manner. [...] I'm

> wondering if it makes sense to have a spinoff project, or find new
> people, who can help build a miner sub-site on bitcoin.org

I think this is an interesting idea. I don't have a good feel for
whether it'll be effective, but I'm I'm willing to commit to a few dozen
hours of writing to it.

> - Explains the basics of mining and in particular *why running
> Bitcoin Core is critical to decentralisation*
> - How to set up p2pool or getblocktemplate based mining where the

> pool doesn't control tx selection

These two I'm willing to do. Saīvann: if you're on board with this,
where on the site do you think this should go? (I'd prefer to keep it
separate from the dev docs.)

> - Perhaps a newbie oriented help forums? bitcointalk, other than

> being a noisy trollfest, is for general discussion and not
> explicitly helping people get set up.

This I prefer to have nothing to do with. I've stumbled upon many
mining-related threads over the years, and they've always focused on
making the most money rather than what's good for anyone else. I don't
want to spend time around that kind of thinking.

-Dave
--
David A. Harding

[Saïvann Carignan]

Le 2014-06-13 15:35, David A. Harding a écrit :
>
>> - Explains the basics of mining and in particular *why running
>> Bitcoin Core is critical to decentralisation*
>> - How to set up p2pool or getblocktemplate based mining where the
>> pool doesn't control tx selection
>
> These two I'm willing to do. Saīvann: if you're on board with this,
> where on the site do you think this should go? (I'd prefer to keep it
> separate from the dev docs.)

I agree this shouldn't be part of dev docs.

How about we actually create a "Keep Bitcoin decentralized" page,
broadly presenting many risks for centralization, their potential
consequences, and solutions users can support or adopt in order to help
avoiding these problems?

I'm not sure this page should be linked in the menus (much like there's
no menu entry for "Secure your wallet" and "Protect your privacy"),
these pages are linked contextually, bitcoin.org already has a good
number of menu entries.

Perhaps it would be worth focusing on what useful content we can provide
that isn't already in pages we are linking from the "Participate" and
"FAQ" page:

http://www.bitcoinmining.com/
http://p2pool.in/

I have already convinced bitcoinmining.com to encourage people to join
smaller pools and P2Pool. And given their domain name, I doubt
bitcoin.org is going to receive this much visitors from interested
miners when typing "Bitcoin mining" on Google.

P2Pool.in provides the most simple instructions, and bitcoin.org
provides instructions for faster block chain download.

I also think that the "Choose your wallet" page probably needs a big
update in order to promote Bitcoin Core more efficiently, which is
something I am working on currently...

Saïvann

[Mike Hearn]

How about we actually create a "Keep Bitcoin decentralized" page,
broadly presenting many risks for centralization, their potential
consequences, and solutions users can support or adopt in order to help
avoiding these problems?

That would be nice, though right now mining is a big enough topic that it could use all the available time.

I think such a page should be in the menus, because the informational content of such a page is only part of the value:  a lot of it comes from the intellectual weight of being on bitcoin.org, being peer reviewed by the developer team and so on. I think it'd have more influence if there was a dedicated miner section that we tried to keep up to date with news and useful tips, etc.

 

P2Pool.in provides the most simple instructions, and bitcoin.org
provides instructions for faster block chain download.

P2Pool is good, but it's not the only way to decentralise mining. I am not sure how much of a role getblocktemplate can play, but in theory it allows people to pool for less payout variance, yet still retain editorial control over what they mine. The problem with pools is not the reduced variance or centralised servers per se, it's that miners lose control over policy.

However I do not know enough about mining to help set that up.

I definitely think we should maybe try recruiting more volunteers. David, Saivann, you guys are unbelievably effective but you can't do everything! Maybe you could use your experience to coordinate rather than write all the material yourselves.

If we come up with a plan, I can try doing some posts and rallying cries to see if any volunteers come out of the woodwork.

[David A. Harding]

On Sun, Jun 15, 2014 at 11:29:53AM +0200, Mike Hearn wrote:
> I think such a page *should* be in the menus, because the informational

> content of such a page is only part of the value:

Let's write the page and then decide where it goes.

> If we come up with a plan, I can try doing some posts and rallying cries to
> see if any volunteers come out of the woodwork.

My plan is always the same: write something and see what happens. I'm
150 lines into a comprehensive guide to mining concepts written for
anyone with a grade-school (primary-school) education. (No compsci
knowledge required.)

It will describe how mining works and why it's essential, the rewards
and risks of mining, the responsibilities of miners, and how to get
started mining. I expect it to take another two weeks to complete, so
expect a pull request (I'll @ mention you) around July 1st.

If there are new volunteers working on a mining tips & tricks section by
then, that'd be cool. If not, I think that'd be ok too---I'd like the
page I'm writing to be strong enough on its own that it becomes an
essential resource for the new miner community.

Thanks,

[Saïvann Carignan]

Le 2014-06-15 05:29, Mike Hearn a écrit :

> though right now mining is a big enough topic that
> it could use all the available time.

It's certainly popular, but I'm afraid we won't have really useful stuff
to say about mining... :( What else can we recommend *right now* that
isn't resumed by this sentence on the "Participate" page?

"You can start mining bitcoins to help processing transactions. In order
to protect the network, you should join <smaller mining pools> and
prefer decentralized pools like <P2Pool> or <pools> with
getblocktemplate (GBT) support."

Here's some content I think can be troublesome, unless perhaps if
there's some good long-term plan;

News: it takes recurring effort to maintain news. I think dedicated
resources like CoinDesk are doing a better job.

Community: (Same reasons David mentioned)

Pools: Like wallets, listing them / doing promotion is controversial and
can become complex or time consuming.

Also, it would be good to translate this page if we want a broader
audience, but this also means it shouldn't change too often.

> I think such a page /should/ be in the menus,

If it goes in the menus, I guess it should be under "Introduction".

Saïvann

[Mike Hearn]

My plan is always the same: write something and see what happens.  I'm
150 lines into a comprehensive guide to mining concepts written for
anyone with a grade-school (primary-school) education.  (No compsci
knowledge required.)

I think what we need right now is not so much a guide to mining concepts (though that is undoubtably good to have), but some kind of lightweight and simple 123 type page that starts, "So, you got yourself an ASIC miner - now what?"

I suspect most miners don't want to do extensive reading to get themselves set up appropriately, what they want are example command lines and tutorials. So that's why I was thinking we could ask for volunteers to help create such a page. 

[David A. Harding]

On Mon, Jun 16, 2014 at 01:57:45PM +0200, Mike Hearn wrote:
> I think what we need right now is [...] some kind of lightweight and

> simple 123 type page that starts, "So, you got yourself an ASIC miner
> - now what?"

A few days after that person sets up their miner using our instructions,
they're going to do the math and realize that they're probably never
going to reach profitability. Then they're going to search the web and
find some guy who says the profits are higher at GHash.io---which might
be true.

Your original email said, "we have a major problem with transmission of
cultural knowledge around mining. Many miners seem to not properly

understand what mining is for, how it works or how to properly mine in a
decentralised manner."

That seems like the essential mission here. We don't want to use
Bitcoin.org's reputation and pagerank to muscle out other getting
started resources---we want to give would-be and new miners the same
facts you and I have:

* That decentralized mining helps prevent double spending; that
centralized mining makes double spending easier; and that Bitcoin has
no use (and thus no value) if double spending is easy.

* That >50% isn't some magic threshold where an attack suddenly
becomes possible, but that attacks rapidly become easier the closer
the attacker gets to 50%.

* That mining is very hard to make a profit on; that it is not a
get-rich-quick scheme.[1]

* The "cloud mining" providers can steal from their customers to a
certain degree without any chance of detection.

* Etc...

To my knowledge, there is no document about mining to which level-headed
people can link knowing that it's accurate, written for laymen, and
doesn't have a hidden agenda.[2] If we publish such a document, I think
it will further enhance Bitcoin.org's reputation rather than just play
on that reputation to get people to setup their mining software the way
we want it setup.

> what they want are example command lines and tutorials. So that's why
> I was thinking we could ask for volunteers to help create such a page.

They surely do want those things, and if you can find volunteers to
create such resources, I think that'd be awesome.

-Dave

[1] This is something that annoys me about bitcoinmining.com---that main
page video has miners sitting in a swimming pool drinking martinis
as gold coins fall into their hands.

[2] More criticism of bitcoinmining.com---it's a very scammy stealth
advertisement for Butterfly Labs.
--
David A. Harding

[Saïvann Carignan]

David's plan sounds good to me so far. Being concise will probably be
key IMO. Replacing bitcoinmining.com link in all translation is easy.

[Greg Sanders]

Agreed. My gut feeling is that 90% of cloudhashing is done by people who hear about Bitcoin and get suckered into thinking they are helping the network and will get some "free money" in return.

A prominent resource on bitcoin.org could have an impact on re-orienting those folks.

[David A. Harding]

On Sun, Jun 15, 2014 at 08:39:36PM -0400, David A. Harding wrote:
> expect a pull request around July 1st.

Progress has been slower than I would've liked and I have to take some
time away from the project to do some extra work for a client, so I'm
bumping the anticipated pull request date back to July 15th.

I'm still trying to finish the first draft, but now that I'm starting to
see my original vision for the document appear on screen, I can't help
but get more and more excited. It could be authorial hubris, but I
think this has the potential to be one of the best resources on the web
for miners.

In other words, I'm having a blast! Thanks everyone for giving me a
chance to work on it!

[Greg Sanders]

Can I get a sneak peak? Checked your github, couldn't find if anything was up.

Greg

--
David A. Harding

--
You received this message because you are subscribed to the Google Groups "bitcoin-documentation" group.

To unsubscribe from this group and stop receiving emails from it, send an email to bitcoin-document...@googlegroups.com.

[David A. Harding]

On Thu, Jun 26, 2014 at 10:58:35AM -0400, Greg Sanders wrote:
> Can I get a sneak peak? Checked your github, couldn't find if anything was
> up.

Er, I really don't like sharing first drafts, especially uncompleted
ones. My writing process allows me to write crap in the first draft
knowing that I'll fix it later in editing, so the content is
particularly unusable. (Not to mention, there are large important parts
missing that I haven't written yet.)

However, I do usually send proof-of-progress to clients when I have to
push back a deadline, so I guess I do owe you something. You can read
the link below, but note that I do not want any feedback---and if anyone
sends some, I'll probably delete it unread. (Writing for me is a
trial-and-error process, and I need to try stuff for myself to see
whether or not it's an error.)

Just to be explicit: DO NOT SEND ME FEEDBACK ON THE DRAFT, please.

http://dg4.dtrt.org/en/mining

(I'm going to delete that upload in about 24 hours so my first draft
crap doesn't spread.)

Thanks,

[Saïvann Carignan]

Oooh!!!

Everything David is touching becomes highly informative :) Thanks for
working on this! (Yeah agreed, it's a draft, no more feedback).

Sorry for my silence, I am also busy these days and working on fixing
many issues on the "Choose your wallet" page, and might also come with
important changes soon.

Saīvann

[David A. Harding]

On Thu, Jun 26, 2014 at 01:19:13PM -0400, Saīvann Carignan wrote:
> Sorry for my silence, I am also busy these days and working on fixing
> many issues on the "Choose your wallet" page, and might also come with
> important changes soon.

Sounds awesome! I suspect that might be the most important page on
the site, but I bet it's also really tricky to get right. Good luck!
(And let me know if there's anything I can do to help.)

[David A. Harding]

On Thu, Jun 26, 2014 at 10:58:35AM -0400, Greg Sanders wrote:

> Can I get a sneak peak? Checked your github, couldn't find if anything was
> up.

I finally finished the text, so I pushed it to a preview branch[1] to my
GitHub.

HTML Preview: http://dg0.dtrt.org/en/mining
Commit: https://github.com/harding/bitcoin.org/commit/f4483d1e111c7b4fee94100fdd91f8610b88bf59
Diff: https://github.com/harding/bitcoin.org/compare/mining?expand=1

I don't have any changes planned to the text between now and the pull
request, so feedback is very welcome---especially if it helps me avoid
embarrassment on the pull request. :-) Emails, commit comments, and pull
requests are all fine.

I'm now working on creating the rest of the illustrations, improving the
existing illustrations, adding links in the guide, adding a few links
from other pages on the site to the guide, and figuring out how to make
Javascript calculators.

The document is not as comprehensive as I had hoped that it would be,
but I think it's still a pretty good introduction to mining that makes
clear the risk of hash rate centralization.

-Dave

[1] I will squash my commits when I finish formatting and push them to a
branch on the main bitcoin.org repository before making the pull
request. That way other people can easily submit pull requests
against the pull request.
--
David A. Harding

[Saïvann Carignan]

Really cool! And *really* glad you spent time making this!!

I'll try to dedicate some time to create a few pull requests over the
next days.

But some quick feedback, in case that makes sense to you:

--

s/it stay/it stays/

s/bock chain/block chain

--

"All miners should be aware of these attacks so that they can help
prevent them, or so they can sell their bitcoins and mining equipment
when an attack threatens to make bitcoins lose too much value."

"All miners should be aware of these attacks so that they can help
prevent them or be prepared."

IMHO the last sentence could be dropped; it may be a bad idea to suggest
people what to do in such scenario since nobody can predict what would
happen, and panic-selling mining hardware could be an unprofitable
decision too. I think the first disclaimer is making it clear that
mining is a risky business and is probably good enough.

--

Also maybe we could put some more emphasis on the fact that if you are
not running a full node, this is not decentralized mining.

(https://bitcoinfoundation.org/2014/07/03/mining-decentralisation-the-low-hanging-fruit/)

Saīvann

[David A. Harding]

On Sun, Jul 13, 2014 at 05:05:46PM -0400, Saīvann Carignan wrote:
> Really cool! And *really* glad you spent time making this!!

Thanks! It was a challenge to write, but that made it all the more fun.

> s/it stay/it stays/

My way sounds right to my ear but your way seems more grammatically
correct, so I rewrote the sentence to avoid the problem altogether.
Thanks!

> s/bock chain/block chain

Thanks! (Things I learned today: bock is in my spell check dictionary
because it's the name of some type of traditional beer.)

> > All miners should be aware of these attacks so that [...]
> > they can sell their bitcoins and mining equipment [...]
>
> IMHO [...] it may be a bad idea to suggest people what to do in such

> scenario since nobody can predict what would happen,

True. Fixed. Thanks!

> Also maybe we could put some more emphasis on the fact that if you are
> not running a full node, this is not decentralized mining.

Excellent suggestion! I created a new Decentralized Mining subsection
and put Solo, P2Pool, and GBT under it. I also moved the list of
decentralized methods from the end of the doc into that subsection,
making things much more tidy. I think this helps improve the structure
of the document significantly, so thanks!

In addition, I described centralized versus decentralized in the
Mining Software subsection. If you see anywhere else I can mention
the connection between full nodes and decentralized mining, please
let me know.

I updated the preview and push a commit to the branch with all the
changes above, but I'm getting sleepy, so I haven't fully reviewed the
changes for good flow or spelling mistakes---I'll do that tomorrow.

Preview: http://dg0.dtrt.org/en/mining
New Commit: https://github.com/harding/bitcoin.org/commit/bae20c60c1357ab4e8df703dce29303587f6860b

Thanks again,

[David A. Harding]

On Mon, Jul 14, 2014 at 01:08:31AM -0400, David A. Harding wrote:
> I haven't fully reviewed the changes for good flow or spelling
> mistakes---I'll do that tomorrow.

Fixed one mistake and added hyperlinks within the document. However,
the real reason I'm posting is to say that I got smart and created a pull
request against my own repository's master branch so that it's easier to
keep track of what work is being done and to make line comments.

Preview Pull Request: https://github.com/harding/bitcoin.org/pull/8
HTML Preview: http://dg0.dtrt.org/en/mining

Feedback is welcome both here on the list and there on the pull.

Thanks!,

[Mike Hearn]

Looks great!

I still think we need parts of the website that are literally just a single page with a few sentences, but this material is excellent for people who are more adept at reading :)

[David A. Harding]

On Tue, Jul 15, 2014 at 12:49:29PM +0200, Mike Hearn wrote:
> Looks great!

Thanks!

> I still think we need parts of the website that are literally just a single
> page with a few sentences

I completely agree. I put a request for help writing mining docs at the
bottom of the guide and bought a cheap used AntMiner so I can write/test
instructions myself if nobody volunteers.

(However, anything I do probably won't be before September---I haven't
touched the devel docs in a month and I'd like to make some progress
there before spending too much more time on mining.)

Thanks for taking the time to look at the guide!,

[Saïvann Carignan]

Still haven't had enough time to review everything, but here's some
additional feedback!

You can also wait for me to submit a pull request too, but I'm not sure
if all of this feedback will make it, or might need to be rewritten
differently.

--

I was thinking a "Mining Hardware" subsection would make sense under
"Tools and Technique", perhaps reusing some texts already under other
subsections, because people really need hardware today to start mining.

And since we don't provide list of mining software/hardware/pools, we
could perhaps prominently link to Luke-Jr wiki pages? These seem to be
kept up to date:

https://en.bitcoin.it/wiki/Mining_hardware_comparison
https://en.bitcoin.it/wiki/Comparison_of_mining_pools
https://en.bitcoin.it/wiki/Mining_software

--

"Users Trust Mining To Validate And Protect Promises"

"Users Trust Mining To Validate And Confirm Promises"

Just an idea, but does the later sound better to you? I was wondering if
we could use something that further suggests promises are irreversible,
"Enforce Promises" could be another one. Although these are just
suggestions, "Protect" is good too IMO!

--

How it works

The Role Of Mining/The Purpose Of Mining/What Is Mining

I was trying to put myself in the shoes of a visitor, and I figured this
title might confuse me into thinking I would find "how to get started"
stuff here rather than "how the system works", so I wondered if one of
the suggested titles here would make more sense?

--

To make promises hard to change, Bitcoin partly solves several problems.
The problems are partly solved because each solution introduces new
problems. By partly solving these new problems, and their sub-problems
(and so on), we arrive at a system where promises can be very hard to
change.

To make promises hard to change, Bitcoin partly solves several problems
using a different system. However, this system also comes with its own
unique problems and challenges.

(I thought this one was a little confusing and could possibly be
simplified.)

--

If each miner can make his own tickets, how do we prevent miners from
making an unlimited number of tickets? Bitcoin makes mining equipment do
work to create tickets, so the more tickets are created, the more work
needs to be done.

f each miner can make his own tickets, how do we prevent miners from
making an unlimited number of tickets? Bitcoin lets miners compete
against each other, by making mining equipment do work to create
tickets, so the more tickets are created, the more work needs to be done.

(I thought "compete" could be used as a good word to explain this in a
very simple way.)

--

What do we do when two or more miners each discover a winning lottery
ticket? Bitcoin lets the miner who wins the next lottery decide which of
the previous winning tickets actually won the previous lottery.

What do we do when two or more miners each discover a winning lottery
ticket? Bitcoin *requires* the miner who wins the next lottery decide
which of the previous winning tickets actually won the previous lottery.

(Subtle suggested change for increased accuracy)

--

How do we discourage dishonest miners from changing the official record
by using their wins in new lotteries to choose their own tickets in old
lotteries? Bitcoin pays lottery winners for the work they do, but if a
miner makes the system unreliable by changing the record, the bitcoins
he earns become less valuable than the work he does, costing him money.

How do we discourage dishonest miners from changing the official record
to defraud users? Bitcoin makes it exponentially difficult to change
previous records by requiring miners to redo work of other miners, and
Bitcoin pays lottery winners for the work they do, but if a miner makes
the system unreliable by changing the record, the bitcoins he earns
become less valuable than the work he does, costing him money.

(I thought some relevant information was missing here)

--

s/which promises won’t be accepted/which promise won’t be accepted

(Small typo I think!)

--

[Saïvann Carignan]

Just a thought, perhaps we can make a page similar to "Bitcoin for
Individuals/Businesses/Developers which basically summarizes mining in
no more than 6 short paragraphs, with the big "Getting started" button
linking to the full Mining documentation?

Saïvann

> <mailto:bitcoin-documentation%2Bunsu...@googlegroups.com>.

> For more options, visit https://groups.google.com/d/optout.
>
>

> --
> You received this message because you are subscribed to the Google
> Groups "bitcoin-documentation" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to bitcoin-document...@googlegroups.com

> <mailto:bitcoin-document...@googlegroups.com>.

[David A. Harding]

On Tue, Jul 15, 2014 at 11:36:00PM -0400, Saīvann Carignan wrote:
> Just a thought, perhaps we can make a page similar to "Bitcoin for
> Individuals/Businesses/Developers which basically summarizes mining in
> no more than 6 short paragraphs, with the big "Getting started" button
> linking to the full Mining documentation?

That's a great idea, and it'll also make it easy to link to other
resources both on Bitcoin.org and off. I'll draft some text and reply
here when I've added it to the preview.

(Re: your other message---lots of good points! I'll reply once I've
integrated as much as I can so we can discuss the rest. No need to send
pulls for any of that.)

[Saïvann Carignan]

Le 2014-07-15 23:48, David A. Harding a écrit :
> On Tue, Jul 15, 2014 at 11:36:00PM -0400, Saīvann Carignan wrote:
>> Just a thought, perhaps we can make a page similar to "Bitcoin for
>> Individuals/Businesses/Developers which basically summarizes mining in
>> no more than 6 short paragraphs, with the big "Getting started" button
>> linking to the full Mining documentation?
>
> That's a great idea, and it'll also make it easy to link to other
> resources both on Bitcoin.org and off. I'll draft some text and reply
> here when I've added it to the preview.

Cool! If this page is short like other "Bitcoin for -" pages, we could
translate it, so we can at least have some key introduction points in
all languages.

> (Re: your other message---lots of good points! I'll reply once I've
> integrated as much as I can so we can discuss the rest. No need to send
> pulls for any of that.)

Great to know it's useful! Thanks for working on all this!

Saïvann

[David A. Harding]

Replies to Saïvann's feedback are below, but I wanted to copy something
from below to where other people might see it:

Fixed. Thanks! And thanks for all of your feedback! In almost 10
years of professional writing, I've never written a document which
hasn't been improved significantly by a good review-based revision.
I really appreciate you taking the time to help me.

I know there aren't many people on this list and that everyone is busy,
but I really do love feedback. If anyone here has a few minutes, please
consider using the links below to make comments and suggestions:

HTML Preview: http://dg0.dtrt.org/en/mining
Pull Request Preview: https://github.com/harding/bitcoin.org/pull/8
Comments can be posted here or on the pull request preview, or you can
send me private email.

On Tue, Jul 15, 2014 at 11:22:46PM -0400, Saïvann Carignan wrote:
> 1. I was thinking a "Mining Hardware" subsection would make sense under

> "Tools and Technique", perhaps reusing some texts already under other
> subsections, because people really need hardware today to start mining.

Note: I numbered your suggestions to help make sure I got them all.

I think this information is already in Mining Software, so I renamed the
section to Hardware And Software.

> https://en.bitcoin.it/wiki/Mining_hardware_comparison
> https://en.bitcoin.it/wiki/Mining_software

I didn't know about these. (I really have to spend a day going through
all the wiki content some time.) I added them to the resources
paragraph in the Hardware And Software section.

> https://en.bitcoin.it/wiki/Comparison_of_mining_pools

This is already in the Pooling section.

I made these changes in this commit:

https://github.com/harding/bitcoin.org/commit/6d9a0b439e2bcb6b7c9ffa3ff8acd0c45ab67850

> 2. "Users Trust Mining To Validate And Protect Promises"
>
> [...] I was wondering if we could use something that further suggests
> promises are irreversible

Good idea. I changed it to, "Mining Validates And Protects Promises So
Users Who Get Paid, Stay Paid".

This and all of the following changes were made in this commit:

https://github.com/harding/bitcoin.org/commit/5db1886ac0d5713fadcaa4cb0f65b90d3dd58e51

> 3. How it works

>
> I was trying to put myself in the shoes of a visitor, and I figured this
> title might confuse me into thinking I would find "how to get started"

Yeah, that could be confusing. I changed it to "Theory." (Which is a
scary term to some people---but perhaps not to anyone likely to read the
document anyway.)

I think I'll try to add a few more links from the later parts of the
document to the earlier parts of the document so that people who skip
Theory can go back to it if they get confused.

> 4. To make promises hard to change, [...]

>
> (I thought this one was a little confusing and could possibly be
> simplified.)

I started working on this, removing things that didn't seem necessary,
and then I tried commenting out the entire Overview section---and I
think it improved the doc. (I'm leaving it commented out for now in case
I change my mind, but I'll delete it before making the pull request.)

I think I'm going to leave in the similar list for the Tools And
Techniques section, although I may rewrite it now that it doesn't need
parallelism with the Overview list.

> 5. If each miner can make his own tickets, [...]
> 6. What do we do when two or more miners each discover a [...]
> 7. How do we discourage dishonest miners from changing [...]

All these refer to now commented-out text. Sorry.

> 8. s/which promises won’t be accepted/which promise won’t be accepted

Fixed. Thanks! And thanks for all of your feedback! In almost 10 years
of professional writing, I've never written a document which hasn't been
improved significantly by a good review-based revision. I really
appreciate you taking the time to help me.

[David A. Harding]

On Tue, Jul 15, 2014 at 11:48:15PM -0400, David A. Harding wrote:
> On Tue, Jul 15, 2014 at 11:36:00PM -0400, Saīvann Carignan wrote:
> > Just a thought, perhaps we can make a page similar to "Bitcoin for
> > Individuals/Businesses/Developers which basically summarizes mining in
> > no more than 6 short paragraphs, with the big "Getting started" button
> > linking to the full Mining documentation?
>
> That's a great idea, and it'll also make it easy to link to other
> resources both on Bitcoin.org and off. I'll draft some text and reply
> here when I've added it to the preview.

I drafted some text for this, but I find it unsatisfactory---I'm not
sure it actually helps anyone. Here's an unedited preview for anyone
who cares:

http://dg0.dtrt.org/en/bitcoin-for-miners

I was wondering if a better template might be the developer
documentation portal page:

https://bitcoin.org/en/developer-documentation

That way we can link to our mining guide for background and to selected
offsite resources like the Bitcoin wiki pages for specific details.
The downside is that there'd be no description text---we'd be assuming
visitors already knew a little bit about mining.

What do ya'll think?

Also, if anyone has a moment, the Javascript calculators could use some
testing. This is the first JS I've ever written, so even though it's
just basic math, there's a fair chance I screwed something up:

http://dg0.dtrt.org/en/mining#calc-diff
http://dg0.dtrt.org/en/mining#calc-percent
http://dg0.dtrt.org/en/mining#calc-income
http://dg0.dtrt.org/en/mining#calc-electricity

Thanks!,

-Dave

[Saïvann Carignan]

Le 2014-07-23 21:38, David A. Harding a écrit :

> On Tue, Jul 15, 2014 at 11:48:15PM -0400, David A. Harding wrote:
>> On Tue, Jul 15, 2014 at 11:36:00PM -0400, Saīvann Carignan wrote:
>>> Just a thought, perhaps we can make a page similar to "Bitcoin for
>>> Individuals/Businesses/Developers which basically summarizes mining in
>>> no more than 6 short paragraphs, with the big "Getting started" button
>>> linking to the full Mining documentation?
>>
>> That's a great idea, and it'll also make it easy to link to other
>> resources both on Bitcoin.org and off. I'll draft some text and reply
>> here when I've added it to the preview.
>
> I drafted some text for this, but I find it unsatisfactory---I'm not
> sure it actually helps anyone. Here's an unedited preview for anyone
> who cares:
>
> http://dg0.dtrt.org/en/bitcoin-for-miners
>
> I was wondering if a better template might be the developer
> documentation portal page:
>
> https://bitcoin.org/en/developer-documentation
>
> That way we can link to our mining guide for background and to selected
> offsite resources like the Bitcoin wiki pages for specific details.
> The downside is that there'd be no description text---we'd be assuming
> visitors already knew a little bit about mining.
>
> What do ya'll think?

As far as I'm concerned, I actually think what you've done is a good
start (but open to other ideas).

I guess what we need is just a concise and accessible introduction here.
So anybody who's wondering "hey, how about I try to become a miner?"
just gets a clear overview of mining in a few sentences before getting
into the details.

Maybe I can help with that. Just adapting texts so they have a
consistent length, avoid punctuations in titles, use consistent colors
in icons, etc. would provide a good experience I think. I've attached an
example with texts to this message in case you find it more inspiring.

The devel-docs layout could work supposing we had enough resources to
link. I fear this isn't the case..

> Also, if anyone has a moment, the Javascript calculators could use some
> testing. This is the first JS I've ever written, so even though it's
> just basic math, there's a fair chance I screwed something up:
>
> http://dg0.dtrt.org/en/mining#calc-diff
> http://dg0.dtrt.org/en/mining#calc-percent
> http://dg0.dtrt.org/en/mining#calc-income
> http://dg0.dtrt.org/en/mining#calc-electricity

Very cool! I'm not good with math, but I'll take a look at the
javascript code when I have a minute.

Saïvann

[Saïvann Carignan]

> Also, if anyone has a moment, the Javascript calculators could use some
> testing. This is the first JS I've ever written, so even though it's
> just basic math, there's a fair chance I screwed something up:
>
> http://dg0.dtrt.org/en/mining#calc-diff
> http://dg0.dtrt.org/en/mining#calc-percent
> http://dg0.dtrt.org/en/mining#calc-income
> http://dg0.dtrt.org/en/mining#calc-electricity

Cool javascript! Very readable! :) I've left a few comments and examples
to help you avoid common bugs and improve a thing or two.

Saïvann

[David A. Harding]

On Wed, Jul 23, 2014 at 10:39:27PM -0400, Saīvann Carignan wrote:
> So anybody who's wondering "hey, how about I try to become a miner?"
> just gets a clear overview of mining in a few sentences before getting
> into the details.

Ah, but why do we need a clear overview of mining in a few sentences
before getting into details? Is the goal to encourage them to mine,
much like we encourage people to use Bitcoin on the other bitcoin-for-X
pages? Is the goal maybe to explain how hard mining really is? E.g.:

Mining requires special hardware
Mining requires special software
Miners must be careful to avoid scams
Equipment is only good for a few months
Price decreases hurt miners worse than others
Dishonest miners can reduce income for honest miners

I like your changes to the draft page, but when I read both yours and
the original, I feel like we're just stating some random facts about
mining without any obvious goal.

> The devel-docs layout could work supposing we had enough resources to
> link. I fear this isn't the case..

I was thinking something like this: (link at the bottom in case it
doesn't format correctly)

Main Link: Mining Guide

THEORY RESOURCES

Background Hardware & Software
~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
What mining does Hardware list (wiki)
Attacks Hardware sub-forum (btctalk)
Software list (wiki)
Software sub-forum (btctalk)

Pooling Pools
~~~~~~~ ~~~~~
Pooling & Shares *Recommended:* P2Pool (p2pool.in)
Decentralized Mining Pool list (wiki)
Pool discussion (btctalk)

Income & Expenses Income & Expenses
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
Difficulty Adjustments Pre-order losses calculator (guide)
Electrical & Cooling Costs Competitiveness calculator (guide)
Pool Costs Gross income calculator (guide)
Compound Profits & Losses Electrical costs calculator (guide)
Scams

Advice Community
~~~~~~ ~~~~~~~~~
Choose To Be Honest Bitcoin Talk Mining Sub-forum
#bitcoin mining IRC

(The above as a text file: http://dtrt.org/tmp/mining-portal.txt )

> I'll take a look at the javascript code when I have a minute.

Thanks so much for your help with this today.

[David A. Harding]

Hey all,

I've been trying out the mining doc on people who stop by #bitcoin IRC
saying they're interested in mining---and none of them have found the
document particularly useful. :-(

The main problem seemed to be the document's length, a problem Mike
warned about from the outset and which I ignored.

I'm going to abandon work on it for now and go back to focusing on the
developer docs. I'm seeing people who don't know me randomly quoting
from the devguide on IRC, so I think it's probably a much more
useful document that's actually getting read.

I'll probably be able to salvage large parts of the mining docs by
moving some parts into the dev docs and other parts into future
(shorter!) mining docs. For now, I'll keep the branch around but delete
the HTML preview and close the preview pull.

Thank you everyone for helping; sorry it didn't work out.

[Saïvann Carignan]

Be sure to save the branch!!

Really did you test it on a good number of people? Newcomers wanting
only super-simple-instructions isn't surprising to me, and likely why so
much miners are ending up on Ghash.io IMO..

I still think your work on this page is worth the effort. But certainly
agree too with developer documentation being a higher priority. A lot of
people love what you've been doing here!

( Sorry BTW for still not having stats :) )

Saïvann

[David A. Harding]

On Sat, Jul 26, 2014 at 11:22:17PM -0400, Saīvann Carignan wrote:
> Really did you test it on a good number of people?

About half a dozen wanna-be miners plus whoever else was in the chatroom
at the time. One of the wanna-bes even asked if there was a book about
mining... and then didn't read the doc.

Paying close attention to the similarities in the questions they asked
made me realize the document is woefully unsuited to their state of
mind. Every single one of them asked either "what equipment do I
buy to make the most money?" or "will I make money if I buy the ____ piece
of equipment?"

If I were to go back in time by a month, I'd tell myself to focus on
making great docs just for P2Pool---maybe screencasts in addition to
text---hopefully lowering the barrier to entry a bit. Then I'd let
other people persuade miners to use P2Pool.

> But certainly agree too with developer documentation being a higher
> priority.

Yeah. I feel like we're falling behind the curve of development
there---all those people who complain about the glacial pace of Bitcoin
Core development should try writing the docs! :-) I'll get us caught up
and then start working on some ideas I have for the devref.

Thanks,