Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Use "free software" terminology consistently #249

Closed
wants to merge 2 commits into
from

Conversation

Projects
None yet
2 participants
Contributor

luke-jr commented Sep 18, 2013

Right now, there's a mix of open-source and free software.

I'm not sure this is a good solution as-is. Maybe we should use "open" for Bitcoin itself (protocols, etc), and "free software" when specifically talking about Bitcoin-Qt etc?

This one is too short. How about adding:

Once the payment has been received, it is a good practice not to reuse previous addresses for privacy and security reasons.

I'd say let's not change this one for now. I generally try to avoid using "miners" except when required because it does not translate well and refers too much to "money issuance", which is not relevant on this context. Fraud detection isn't only required for high-value transactions, and I think the "no PCI" subject should be treated seperately.

Owner

luke-jr replied Sep 19, 2013

Fraud detection is often necessary for low-value transactions which are being accepted without confirmation.

OK I see what you mean. How about:

Most parts of the security are handled by the protocol on the client and Bitcoin network side. Authenticity is verified with digital signatures, and chargebacks are prevented by the Bitcoin network after a short delay. That means no need for PCI compliance and fraud detection is only required when services or products are delivered instantly.

Actually, I think this one should be rewritten. How about:

Your Bitcoin wallet is what allows you to transact with other users. It gives you ownership of a Bitcoin balance and lets you send and receive bitcoins using different Bitcoin addresses for each new payments. Just like email, all wallets are interoperable with each other. Before you start with Bitcoin, be sure to read what you need to know first.

This one puts a bit less emphasis on addresses.

Your Bitcoin wallet is what allows you to transact with other users. It gives you ownership of a Bitcoin balance and lets you send and receive bitcoins using a unique address for each new payment. Just like email, all wallets are interoperable with each other. Before you start with Bitcoin, be sure to <b><a href="#you-need-to-know#">read what you need to know</a></b> first.

This one is hidden because the website is down since quite a while and maintaining the app seems to be their lowest priority. I'd say let's not change this one. I will simply drop it in a seperate commit.

Shouldn't it actually be "no web wallet service provides" ?

Owner

luke-jr replied Sep 19, 2013

Probably valid either way, but this sounds more natural IMO.

Fine then.

Not mentionning Bitcoin addresses makes the explanation incomplete. How about:

"From a user perspective, Bitcoin is nothing more than a mobile app or computer program that provides a personal wallet and allows a user to send and receive bitcoins using Bitcoin addresses. This is how Bitcoin works for most users."
Owner

luke-jr replied Sep 19, 2013

I don't think it does. Consider that users might use Bitcoin without ever seeing an address (payment protocol, QR codes, URIs, etc).

ACK on your version. I didn't think we were close to "obfuscate" the addresses anytime soon.

A bit too long for the available space. However, if you just remove "their half of", it fits correctly.

The "no PCI" subject could be treated seperately.

Owner

luke-jr replied Sep 19, 2013

Even if unnecessary, I don't think PCI compliance is on-topic here as a risk?

Well, I think it is. PCI compliance is a complex standard to manage that risk, so it's closely related. Let's handle this seperately so we can push other improvements.

Did you mean "Bitcoin programs"?

A bit too long for the available space, how about:

Bitcoin is designed to allow its users to send and receive payments with an acceptable level of privacy as well as any other form of money. However, Bitcoin is not anonymous and cannot offer the same level of privacy as cash. The use of Bitcoin leaves extensive public records. Various mechanisms exist to protect users' privacy, and more are in development. However, there is still work to be done before these features are used correctly by most Bitcoin users.

I think we shouldn't say "specifically" there. Some legislation could indirectly make Bitcoin illegal (not by name) and yet there doesn't seem to be such case so far.

Owner

luke-jr replied Sep 19, 2013

A ban on all foreign currency would seem to indirectly make Bitcoin illegal?

The case of Argentina (as stated) is uncertain, indeed. But no new law have been passed against Bitcoin, virtual currencies, or some properties of virtual currencies. So, jurisprudence is missing there and could emerge over time. This text was reviewed and fixed by a law student so I would retain myself to change it except under the advise of someone in the fields.

Your version is better. Shouldn't we keep a mention about the requirement of a strong majority? How about:

The Bitcoin protocol itself cannot be modified without the cooperation of a strong majority its users, who choose what software they use.

An uppercase B is used in "Bitcoin mining" everywhere, but to me it seems that both a lowercase or uppercase b are possible (correct me if I'm wrong). So if this one needs to be fixed, it could be better to fix them all at once in a seperate commit.

I would prefer to stick to the language used by most Bitcoin clients here (6 confirmations and not 6 blocks).

Owner

luke-jr replied Sep 19, 2013

This kind of language leads to confusion when people assume it actually means confirmation.

I understand what you mean but I don't think this one is as much a problem, or that the suggested replacement is better. Better explaining the "6 or more confirmation" idea is enough IMO. Users already see multiple confirmations in their Bitcoin-Qt / BW4A UI with a friendly red-yellow-green or pizza circle for the first 6 confirmations. "Block" is a technical term that isn't found in the apps UI, so I think it's going to be confusing.

A bit too long for the available space, just using "known as ASICs" instead of "known as Bitcoin mining ASICs" would do the trick.

With the new FAQ and getting started page, I think this one should be shortened. How about:

As a new user, you can <a href="#getting-started#">get started</a> with Bitcoin without understanding the technical details. Once you have installed a Bitcoin wallet on your computer or mobile phone, it will generate your first Bitcoin address and you can create more whenever you need one. You can disclose one of your addresses to your friends so that they can pay you or vice versa. In fact, this is pretty similar to how email works, except that Bitcoin addresses should only be used once.

I'd prefer to keep "Balances" here. "Coins" don't translate well and it lets people think they have a coin in their computer. It is more accurate for them to think their wallet just show balances.

Owner

luke-jr replied Sep 19, 2013

But this isn't talking about their wallet, it's talking about the blockchain, which doesn't have balances.

Perhaps the associated text indeed isn't relevant enough with the title. We could say something like:

This way, Bitcoin wallets can calculate their spendable balance and new transactions can be verified to be spending bitcoins that are actually owned by the spender.

Bitcoins are transaction outputs stored in the block chain. The closest understandable word I see for this system is "Balances". The idea is to help people to understand that Bitcoin balances are stored remotely ( something anyone using online banking will understand ), and bitcoins are not like physical coins stored as files in a computer ( you cannot copy a coin, make safe offline transactions, etc ). The technical details about how these balances are named and managed in the block chain are better explained on the Wiki and Satoshi paper.

Owner

luke-jr replied Sep 20, 2013

But they're not stored as balances. If an analogy is needed, it would be coins in a safe deposit box.

Since you change this one, I would suggest to replace "shared public transaction log" by "shared public ledger". It seems the later is more used.

I think we should keep mentionning addresses here. Also perhaps we should be more specific and say "is usually confirmed by the network in the following ten minutes on average" rather than "in the following hour".

Owner

luke-jr replied Sep 19, 2013

All 3 mentions of addresses here are incorrect.

It's an hour on average before the transaction is actually confirmed.

OK, let's hide addresses to the user here. However, let's use "usually start to receive confirmations by the network in the following minutes", otherwise there is many other places where this should be changed as well and as you pointed out earlier, it's up to each individual to define when they consider a transaction confirmed.

A transaction is <b>a transfer of value between Bitcoin wallets</b> that gets included in the block chain. Bitcoin wallets keep a secret piece of data called a <a href=\"#vocabulary##[vocabulary.privatekey]\"><i>private key</i></a> or seed, which is used to sign transactions, providing a mathematical proof that they have come from the owner of the wallet. The <a href=\"#vocabulary##[vocabulary.signature]\"><i>signature</i></a> also prevents the transaction from being altered by anybody once it has been issued. All transactions are broadcast between users and usually start to receive confirmations by the network in the following minutes, through a process called <a href=\"#vocabulary##[vocabulary.mining]\"><i>mining</i></a>.

This page is being rewritten, I will include your changes in the new version. Meanwhile, it's better not to ask translators to uselessly re-translate these strings if they are going to change a few weeks afterwhile.

Owner

luke-jr replied Sep 19, 2013

Translators don't need to re-translate this if they already got it right the first time...

ACK

This page is being rewritten, I will include your changes in the new version. Meanwhile, it's better not to ask translators to uselessly re-translate these strings if they are going to change a few weeks afterwhile.

This page is being rewritten, I will include your changes in the new version. Meanwhile, it's better not to ask translators to uselessly re-translate these strings if they are going to change a few weeks afterwhile.

This advice is out of reach for many users. I suggest taking the best parts of both texts:

Any password that contains only letters or recognizable words can be considered very weak and easy to break. A strong password must contain letters, numbers, punctuation marks and must be at least 16 characters long. The most secure passwords are those generated by programs designed specifically for that purpose. Strong passwords are usually harder to remember, so you should take care in memorising it.
Owner

luke-jr replied Sep 19, 2013

Out of reach or not, humans simply cannot generate strong passwords. Future wallet software should include passphrase generators (BIP 39).

Great. But until then, let's help all kind of users to choose stronger passwords and recommend password generators as the best solution.

Little typo here I think. Similar to a physical address.

This one should be split in two paragraphs. I can take care of this once everything else is fixed.

I think we should not use the word block without explanation. How about:

A confirmation means that a transaction has been <b>processed by the network and is highly unlikely to be reversed</b>. Transactions receive a confirmation when they are included in a <a href=\"#vocabulary##[vocabulary.block]\">block</a> and for each subsequent block. Even a single confirmation can be considered secure for low value transactions, although for larger amounts like 1000 US$, it makes sense to wait for 6 confirmations or more. Each confirmation <i>exponentially</i> decreases the risk of a reversed transaction.

I think we should actually remove insistance on Bitcoin address but still mention them otherwise the text isn't very clear. How about:

A private key is a <b>secret piece of data that proves your right to spend bitcoins</b> with a specific Bitcoin <a href=\"#[vocabulary.address]\">address</a> by using a cryptographic <a href=\"#[vocabulary.signature]\">signature</a. Your private keys are stored in your wallet on your computer, unless you are using a web wallet service to host your wallet online. Private keys is not something designed to interact with users and most users shouldn't be aware of them. Private keys should never be revealed as they allow you to spend bitcoins.
Owner

luke-jr replied Sep 19, 2013

Private keys have nothing to do with addresses, so any mention of them here is wrong.

ACK on your version

I think we shouldn't change this one.

Owner

luke-jr replied Sep 19, 2013

It's not correct as-is.

Two fixes:

matches the bitcoins being spent
vocabulary.wallet (the anchor link should point to "wallet" and not "address")

Otherwise, ACK on your version

I'd say let's replace "coins" by "bitcoins" in this one, easier to translate and more consistent with the rest of the website.

This page is being rewritten with the "Protect your privacy" page, I will include your changes in the new version. Meanwhile, it's better not to ask translators to uselessly re-translate these strings when they are going to change a few weeks afterwhile.

I would prefer to stick to the language used by most Bitcoin clients here (6 confirmations and not 6 blocks).

@saivann saivann closed this in 15e75cb Sep 27, 2013

Contributor

saivann commented Sep 27, 2013

I think that your proposition makes sense.

Though when it's unclear if we speak about the protocol or the software, I would use open-source by default. In most cases, the argument is that it's open (and auditable) and I think we should be careful with the word "free" (people shouldn't be left thinking that Bitcoin has anything to do with "free money" as in "free beer").

I just pushed a commit to fix this, please re-open the issue if you see anything else you think is worth additional changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment