Update Text on "You Need to Know"

[harding]

Although the text is my own (so blame me if it stinks), the idea for these changes came from @saivann here and here.

[saivann]

@harding I like it!

For brevity, (I always try to fit text within 4 lines, and never exceed 5 lines), how about we merge the first lines together?

Additionally, I think the 10 minutes approximation is pretty useful and important information, even if it possible that it might need to be revised in the near future.

Here's an example with these changes:

New transactions start out as unconfirmed. Unless you trust the person paying you,
you should always wait for the transaction to receive at least one confirmation, which
takes 10 minutes on average. This has historically provided a better than 95% garantee
that the payment can't be changed. This guarantee isn't as strong for lightweight wallets,
so you may want to wait for three confirmations unless you use a recent version of
Bitcoin Core. For high value amounts, waiting for six or more confirmations is strongly
recommended no matter what wallet you use.

[harding]

@saivann rather than try to pack all that information into a paragraph, how do you feel about using a table? Here's an example; it's about 50% taller than your 5-line recommendation but it has lots of white space and I think it's much more readable:

Although I dislike using abbreviations, I used "confs." so that it would look good on even the least-wide mobiles:

"Emergencies" links to the alerts overview page with its RSS feed.

If you think this is reasonable, I'll turn it into translatable strings and add it to this PR.

[saivann]

@harding That makes a lot of sense, that's clearer (and shorter, actually. Taking space on the page isn't really a problem)

Maybe it's possible to mention the 10 minute delay and the nature of the risk in the short paragraph? The example below fits on two lines.

New transactions start out as unconfirmed and only become irreversible after receiving 
enough confirmations. Each confirmation takes 10 minutes on average, and how many
you should wait for depends on your situation:

[saivann]

@harding I use to refer to this paragraph as the "anything can happen" clause. By giving examples, I feel like we're weakening that wildcard warning. How about we simply add the following line:

Several features, such as low fees and fast confirmations, or even the
system as a whole, could suffer severe issues as Bitcoin scales up.

[ABISprotocol]

Hold this open for longer than you would be used to doing, please. You need to wait for more public comment on the matter, even if it seems to you that you should just create it and merge it.

[btcdrak]

I think better than saying "Unconfirmed transactions are not secure" you should say "Unconfirmed transactions are not final and maybe reversed".

Point of order, unconfirmed transactions are simply unconfirmed and subject to change until they are confirmed, they are not "insecure" which means something else entirely.

[harding]

@btcdrak what do you think about me changing the section title to, "Use confirmations to prevent fraud"?

[saivann]

@btcdrak Mmh, if you can be defrauded, and can't rely on them, I think it's accurate to say unconfirmed transactions are not secure. But I'd be fine with "Unconfirmed transactions cannot be trusted" (Edit: or a short version of your suggestion "Unconfirmed transactions may be reversed"), I'm not sure though if that makes a real difference and is worth re-translating?

[harding]

@saivann updated regarding both of your comments. New sections look like this:

(Almost everything in the screenshot above is now changed from the original.)

• I added the information about the confirmations, but used my own wording.
• Except for the first sentence, I completely rewrote the Experimental section. It now mentions increased fees and slower confirmations, but I think it also keeps its "anything can happen" vibe.
• I didn't change the section title. I think calling unconfirmed transactions insecure in the title is fine since the nice table immediately below that clarifies when they're insecure.
• In the table, "confirmations" uses a soft hyphen so it looks reasonable good on mobiles (or at least in Firefox's mobile preview).

[saivann]

How about "The speed of the first confirmation can vary based on how the network is busy and how big a transaction fee you pay, and usually takes 10 minutes on average"

(People mostly care about the first confirmation when it comes to getting an estimation and ~10 minutes seems still accurate: https://blockchain.info/charts/avg-confirmation-time , while still mentioning why it could be longer than that as I think was one of the purposes here ).

FWIW, I didn't notice the second text after the table at a first glance, perhaps it would be more readable if merged with the one right before the table?

Re: Bitcoin is still experimental: FWIW, I really liked the previous "Nobody can predict it's future" conclusion because it encompassed virtually everything, from speculative crashs, technical failures, social phenomenons, or anything impredictable we might not be thinking about.

I must say I am a bit conflicted about saying users are a burden; they are, but it's unclear if they bring more than they take, as Bitcoin is also nothing without users, so there is a dichotomy. I don't know if that comment of mine is really worth thinking though, maybe I'm being too meticulous.

[harding]

@saivann tweaked text in commit 4f90685:

• I tried merging the paragraph below the table into the paragraph above the table, but I didn't feel it was right so I kept them separate. However, I don't think it's important either way, so let me know if you want them merged.

• I revised the paragraph below the table; it now reads:

  Each confirmation takes between a few seconds and 90 minutes, with 10 minutes being the average. If the transaction pays too low a fee or depends on another unconfirmed transaction, getting the first confirmation can take much longer.

• You were right that calling users a burden is, if nothing else, impolite. I changed the phrasing without changing the meaning. I also added 'nobody can predict' back on to the end. Here's the revised paragraph with revisions bolded:

  Bitcoin is an experimental new currency that is in active development. Each improvement makes Bitcoin more appealing—but a growing user base presents new challenges that require more experimentation and development to overcome. During Bitcoin's growing pains you might encounter increased fees, slower confirmations, or even more severe issues. Be prepared for problems and consult a technical expert before making any major investments, but keep in mind that nobody can predict Bitcoin's future.

[harding]

Oh, I forgot. Here is a quick chart I made of the number of blocks per year that take longer than x minutes to produce. I used this formula to chose 90 minutes as the listed maximum (an estimated 6 blocks per year take longer than 90 minutes), but if anyone wants to suggest changing the number, looking at the chart might be useful. The y axis is log scale.

[saivann]

I think the "Experimental" text is much better, and it could be shortened to 4 lines by using a more concise "presents new challenges to overcome" line.

Bitcoin is an experimental new currency that is in active development. Each improvement makes
Bitcoin more appealing—but a growing user base presents new challenges to overcome. During
Bitcoin's growing pains you might encounter increased fees, slower confirmations, or even more
severe issues. Be prepared for problems and consult a technical expert before making any major
investments, but keep in mind that nobody can predict Bitcoin's future.

Re: one/two line paragraph before and after the table; Yes I think it's not a fantastically readable layout.

Re: 10 minutes delay; Thanks for thinking of common issues. New text looks good! I'm fine with "or depends on another unconfirmed transaction" but as it's probably less common and there are other cases where confirmations may take longer, maybe it's broader to just say "or if your transaction does not follow usual transaction pattern" or similar? Just an idea.

[harding]

@saivann updated again. Screenshot of current text below and list of changes below that:

• Revised Experimental text along the lines you described and further condensed it.
• Merged paragraphs above and below table into one paragraph. I added "(see table below)" to the second sentence to make it clear that the table describes number of confirmations and not time to confirmation.
• Used your suggestion for replacing "depends on another transaction" with "is otherwise atypical".

[saivann]

I think the content is more useful for the user, accurate and professional than before, thanks for your careful writing and for taking my feedback into account!

Unimportant stuff that shouldn't block the PR: I wonder if we can increase bottom/top margins a bit on the table to aerate the layout, and if we can drop a word somewhere to avoid having a mostly empty line with a single word ("longer") on it.

[harding]

@saivann I removed "below" from "see table below" to remove the widowing and put a <br> before and after the table. (I think a CSS rule for just one table might be overkill.) I also rebased and squashed again. Preview below.

This PR is scheduled to be merged Sunday, August 2nd. (This provides the extra time for feedback requested by @ABISprotocol)

[btcdrak]

@saivann @harding Regarding "secure".

The use of the word secure here is really misleading. When something is not secure it means that security can be circumvented by an authorised person. Unconfirmed transactions are not insecure, they are simply not final and can be reversed.

Alternative suggestions:

"Unconfimed transactions are not final".
"Unconfimed transactions are reversible".

It's exactly like receiving payment by check, it's not final until the check clears.

I also think the chart is not really giving the full picture because the number of confirmations depends on the risks you are willing to take based on the transaction amount.

[harding]

@btcdrak I don't think the section title is misleading anyone.

Regarding the table, I don't have any ideas for providing better guidelines while staying concise. If you have any suggestions, I'm happy to hear them.

[saivann]

This pull request doesn't change the title anyway so I think it's a separate issue. But FWIW, IIRC this title was previously changed in a PR to explicitely say "isn't secure", so I'm not sure if changing it again really makes sense. Edit: ...And the example provided (checks) aren't considered as a safe form of payment by most merchants either, I still think current title, or alternative suggestions, are both fine.

Regarding the table, I also wonder what could be done that would be better, and in either case, it's still much better than what we have now. If for any reason it is not perfect, it's not set in stone, but someone has to make a better alternative and take time to submit it.