DevDocs corrections part 1 #589

luke-jr · Oct 1, 2014

Started reviewing the developer docs, finding lots of things to correct. I'll do more later, but please review this batch first so I know what, if anything, needs to be fixed moving forward - I'm not entirely sure on the markdownish format used.

We settled on using "satoshi" as the term of generic value. See the style guide and the issue where we discussed this

That sounds fair for cases where units are relevant, but that isn't the case here... In this context, it is just unnecessarily confusing to specify any unit.

Sure, but a bitcoin is also a specific unit of value. In the discussion linked to above we tried to find a term for generic value which had no unwanted connotations, but we failed. In the end, we decided that we'd either have to use "bitcoin" or "satoshi", and so we (basically) flipped a coin and "satoshi" won.

I'd prefer to stick with the previous decision rather than update all the text and illustrations.

Ok.

Actually AFAIK, Merkle tree should be capitalized (the concept is named after Ralph Merkle).

Common nouns are lowercase in English, unless the first word of a sentence. Many things are named after people, but those common nouns don't get exceptions from this rule.

That's good with me then, although I didn't check if all occurences were replaced.

These two sentences were written before we had a Transactions section, and I think we explain everything better there, so I suggest we simply delete lines 45 and 46.

I tend to agree, this one sounds a bit confusing to me.

What is the reason for adding "a value of" here? The original wording seems more direct and both wordings seem equally unambiguous. (Note: I'd like to replace that big ugly illustration at some point, so there will be opportunity for rephrasing later.)

Avoiding "satoshis". Considering the style guide you pointed to, it does make sense to go back to "satoshis" in this one context.

Although it's not currently mentioned in the style guide (I'll update it), we use Microsoft Technical Style for headings and subheads, in which the first letter of each word is capitalized unless it's a proper noun that starts lowercased (e.g. iPhone). The same style is also used for illustration captions and abbreviation expansions.

Why not use standard English? :|

Both forms are standard English, just as you can use or not use a comma before the final conjunction in list (one, two, and three). Here's a page which describes different capitialization styles (we use number 4): http://www.quickanddirtytips.com/education/grammar/capitalizing-titles?page=all

All the text and images use the style described in the Microsoft Style Guide ( https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style_for_Technical_Publications ) for the simple reason that it's the style I learned early in my career. I don't really care what style we use, but I'd prefer not to update everything for so minor an issue.

I think this issue is not a big deal, let's keep what is already used everywhere.

Suggestions:

s/a linear/in a linear/ (seems like the better usage)
s/, on average,/ (on average)/ (I try to avoid comma-based parenthetical when other comma-based sentence divisions are being used)

"in a linear" makes no sense grammatically there...

This is a minor issue, but I feel the block chain is an inert thing which is operated on by peers, so it would be incorrect to say the block chain expects something but correct to say that peers or the p2p network expect that thing.

The full nodes only enforce the preset rules. There is nothing inherently connected to the peer-to-peer network here.

Then how about saying, "difficulty value expected by full nodes on the network"?

I don't think we need to turn every case of "consensus rules" into "expected by full nodes on the network"... This is so fundamental to the system.

Then how about, "difficulty value expected by the network consensus". As stated in my original comment, my (minor) issue is with treating the block chain as an animate object that has expectations. To me, the block chain is just a collection of data, like the log files on my computer.

Part of that data is the required target for new blocks. But "difficulty value expected by the consensus protocol" would work too.

That sounds good to me. Thanks.

I suggest undoing this change as the immediate following bullets explain in more detail what happens.

Minor style suggestion: change "transaction history (although [...] attacks)." to "transaction history. (Although [...] attacks.)"

That suggestion is improper English...

It seems like an independent clause to me. Although, it should be noted, that it would be better if "it should be noted" was placed in parenthetical commas.

A few comments:

I don't mind using the term "stale blocks", but we need to at least introduce the commonly-used term "orphan" (verb) for people that search for that term. I suggest: "throw away (orphan) stale blocks"
The parenthesis around "(stale blocks)" should be dropped so the sentence reads, "throw away stale blocks"

"Orphan blocks" are another thing entirely (blocks with no known parent block).

Perhaps, but many other people use "orphan" and "orphan block" to refer to blocks no longer on the best chain. It would be nice if people expecting those terms could search the page and be taken to the location where we explain what term we use.

Pieter gave a good explanation about the overlapping vocabulary here, I agree this case is a bit messy;
http://bitcoin.stackexchange.com/a/5869

Maybe this is another signal that a technical glossary would indeed be useful, as recently suggested on the mailing list: https://groups.google.com/forum/#!topic/bitcoin-documentation/s_mL1syxYoQ

We originally used the term "generation transaction" but @mikehearn suggested we use "coinbase transaction". I suggest we make sure both terms are introduced to help people searching based on a particular term but that we continue to use "coinbase" unless a discussion is held to change it.

The "coinbase" refers to the scriptSig in the generation transaction. I am probably at fault for using "coinbasetxn" in GBT, but I think it's best to use clearer terminology, even if we have a ("coinbase transaction") in quotes once to avoid confusion.

I think I prefer "generation transaction" and none of our images use the term "coinbase transaction" (I hate updating images because they create binary bloat in the repository), so I have no problems changing the term in the docs---except that two expert developers have each recommended against the term used by the other developer.

I suggest we revert the generation transaction changes in this pull and open a new pull that globally s/coinbase transaction/generation transaction/ (where appropriate with respect to code). Then we can get this pull merged and try to solicit additional opinions from experts about terms on the new pull.

"coinbase transaction" is 3.5 times more used according to Google than "generation transaction" and merging the current pull request would make us inconsistently use both terms, so indeed I think we should revert this and open a seperate pull req so this doesn't block all other useful changes (if @luke-jr doesn't have time, I or @harding could revert this before merging).

I don't understand what this sentence is saying, although I'm guessing it has something to do with BIP30. Could you please clarify?

Actually, CVE-2012-2459. Without this clarification, it is possible to have the same merkle root for multiple different merkle trees - one where the last element exists once, and one where there are two of the same element.

Thanks for the link! Do you think we could more simply say? "Duplicate txids are not permitted."

Or perhaps, "Duplicated txids are not permitted anywhere in the block chain, with the exception of two cases described by BIP30."

This seems to address the problems described by both BIP30 and the linked CVE.

BIP 30 is technically obsolete at this point. Actually checking for duplicate txids would have too much overhead. It's better to simply state the fact that it isn't practical to have them.

My problem is that I'm having a hard time parsing the sentence, so I'm looking for a way to rephrase. Maybe: "Note: two identical txids cannot be paired together because this would produce the same hash as a single txid being paired with a copy of itself. Since it is impractical to have separate transactions with identical txids, this does not impose a burden on honest programs but can prevent certain attacks."

Does the new one address your concerns?

I like what you did in example_intro.md by changing "Bitcoin Forum" to "BitcoinTalk Forum". Perhaps we can do something similar here instead of dropping the reference to the forum altogether. (Although I agree that the forum has its warts, it still seems useful enough to deserve a highly-placed mention.)

BitcoinTalk is pretty much entirely abandoned for development purposes.

How about we link instead to the Bitcoin.org Community page? https://bitcoin.org/en/community

For example, the sentence could say: "If you have questions, you can contact other developers through some of the resources listed on the Community page."

Mmh, to be honest, I think most links on the Community page aren't really suitable for developers. IMO renaming "Bitcoin Forum" to "BitcoinTalk" would be fine, BitcoinTalk isn't used much for development, but that still looks like an useful place to ask technical questions.

I think you're likely to get the wrong answers if you ask technical questions on a place where technical people don't read...

@luke-jr To your experience, the people commenting on the "Development and Technical" board, although not involved with Bitcoin Core, don't have a good technical understanding of Bitcoin? In any case, I have no strong opinion on this.

I don't regularly read the board anymore, so I honestly can't state for certain. The few times I've seen posts there in the last few months, that did appear to be the case, however.

It seems to me that the appropriate thing to do is to allow this change and then, at some point in the future, create a pull adding a section to the docs (or some other page on the site) describing additional places devs can find help, such as the StackExchange.

@harding Agreed!

harding · Oct 1, 2014

@luke-jr I just finished a first-pass review, and in general I like the changes. Thanks!

I think the autocrossref links need to be updated and there are a few minor grammar changes I'd like to make, so I'll try to send a pull request to your branch later tonight. Thanks again!

saivann · Oct 1, 2014

The public key in commit d5babd is correct.

This is incorrect. If the max is 2255 and the target is anything less than 2255, then you should get less than 2**255 practically all the time. I suggest restoring the original phrasing of lines 94 and 95.

The max is 2^256-1, so 2^255 is approximately half that.

I thought so, but you changed line 90 to say, "the maximum possible hash value is 2**255". Maybe that's the line which should be reverted.

Ah yes, I misread that as "maximum accepted hash value". Will fix.

luke-jr · Oct 2, 2014

Conclusions thus far are applied to the branch.

I like the additional detail, but I have some concerns:

The phrasing of the first sentence hasn't changed, so I still have a hard time parsing it.
A paragraph or other extended description here is suboptimal as the next paragraph starts with "For example". The example is of merkle tree creation, not checking for block hash collision.

My suggestions:

Move the new paragraph down to line 225 (in the original numbering) after the {% autocrossref %}.
Rephrase. Here's a modified version of the text I suggested earlier: "Note: two identical txids cannot be paired together because this would produce the same hash as a single txid being paired with a copy of itself. Since it is impractical to have separate transactions with identical txids, this does not impose a burden on honest programs but can prevent bugs such as CVE-2012-2459 from damaging the network."

A B C D E F E F would also create a problem.

luke-jr · Oct 2, 2014

How's this?

saivann · Oct 2, 2014

@luke-jr I just sent you a pull req to fix a broken reference link. I'll take a look at everything else tomorrow, thanks again!

luke-jr · Oct 2, 2014

@saivann Merged

Parenthesis need to be removed from this line. For searchers, I think it would also be nice if this sentence was followed by something like: "(Stale blocks are also sometimes called orphans, but that term is also used for blocks without a known parent block.)"

Thanks! ACK this version of the pararaph.

harding · Oct 2, 2014

I just re-reviewed everything and added just three content-change suggestions, so I think we're close to mergability.

@luke-jr you seem to be revising all sentences inside parenthesis, but when I do a web search for are sentences allowed in parenthesis, I don't see anyone arguing against them. (Almost all of the articles are about period location relative to the close-parens.) I suggest we address this issue before you continue editing to avoid future debate.

saivann · Oct 2, 2014

Except for the last comments from me and @harding, this LGTM.

luke-jr · Oct 3, 2014

Merged in changes

harding · Oct 3, 2014

@luke-jr thanks!

I just completed a final check and this LGTM. @saivann, since you verified the GPG pubkey, I suggest you manage this merge.

luke-jr added some commits Oct 1, 2014

Add PGP key for Luke Dashjr (BD02942421F4889F)

d5babd7

DevDocs: Don't recommend BitcoinTalk

9d01c3a

Refer to BitcoinTalk by name

00ccadb

harding added a commit to harding/bitcoin.org that referenced this pull request Oct 3, 2014

Small Changes To Prepare Pull #589 For Merge

This commit was signed with a verified signature.

harding David A. Harding

GPG key ID: 4B29C30FF29EC4B7 Learn about signing commits

6570317

harding referenced this pull request in luke-jr/bitcoin.org Oct 3, 2014
Merged
Small Changes To Prepare Pull #589 For Merge #2

luke-jr added a commit to luke-jr/bitcoin.org that referenced this pull request Oct 3, 2014

Merge pull request #2 from harding/final-changes
Small Changes To Prepare Pull #589 For Merge

856e1e5

luke-jr added some commits Oct 1, 2014

DevDocs: Block Chain: Block Height and Forking: Many corrections

66edff8

DevDocs: Block Chain: Transaction Data: Many corrections

f85c631

saivann merged commit f85c631 into bitcoin-dot-org:master Oct 3, 2014

This was referenced Oct 4, 2014

Merged

Add "Developer Communities" To Development Page #595

Merged

Mention Bitcoin's RPC Hash Byte Order #583

      stores the hash of the previous block's header, chaining the blocks
      together. This ensures a transaction cannot be modified without
      modifying the block that records it and all following blocks.
      Transactions are also chained together. Bitcoin wallet software gives
-    -the impression that satoshis are sent from and to addresses, but
-    -bitcoins really move from transaction to transaction. Each standard
-    -transaction spends the satoshis previously spent in one or more earlier
+    +the impression that bitcoins are sent from and to wallets, but
+    +bitcoins really move from transaction to transaction. Each
+    +transaction spends the bitcoins previously received in one or more earlier

@@ -20,56 +20,56 @@ A [block][]{:#term-block}{:.term} of one or more new transactions
      is collected into the transaction data part of a block.
      Copies of each transaction are hashed, and the hashes are then paired,
      hashed, paired again, and hashed again until a single hash remains, the
-    -[Merkle root][]{:#term-merkle-root}{:.term} of a Merkle tree.
+    +[merkle root][]{:#term-merkle-root}{:.term} of a merkle tree.

-    -Outputs are not the same as Bitcoin addresses. You can use the same
-    -address in multiple transactions, but you can only use each output once.
+    +Outputs are not the same as Bitcoin addresses.
+    +Once bitcoins are sent, they remain associated with the output until later spent, while the association with a given address ends the moment it is received.

      transaction's inputs and outputs is given as a [transaction fee][]{:#term-transaction-fee}{:.term} to
      the Bitcoin [miner][]{:#term-miner}{:.term} who creates the block containing that transaction.
-    -For example, in the illustration above, each transaction spends 10,000 satoshis
-    -fewer than it receives from its combined inputs, effectively paying a 10,000
-    -satoshi transaction fee.
+    +For example, in the illustration above, each transaction spends a value of 10,000 (0.0001 BTC)

      that a given hash attempt will generate a number below the [target][]{:#term-target}{:.term}
-    -threshold. Bitcoin itself does not track probabilities but instead
-    -simply assumes that the lower it makes the target threshold, the more
-    -hash attempts, on average, will need to be tried.
+    +threshold.
+    +Bitcoin assumes a linear probability that the lower it makes the target threshold, the more hash attempts, on average, will need to be tried.

bitcoin-dot-org/bitcoin.org

Join GitHub today

DevDocs corrections part 1 #589

Conversation

luke-jr commented Oct 1, 2014

luke-jr added some commits Oct 1, 2014

Show 4 comments Hide comments harding and 1 other commented on an outdated diff Oct 1, 2014

saivann commented on the diff Oct 1, 2014

Show 2 comments Hide comments harding and 1 other commented on an outdated diff Oct 1, 2014

Show 2 comments Hide comments harding and 1 other commented on an outdated diff Oct 1, 2014

Show 4 comments Hide comments harding and 2 others commented on an outdated diff Oct 1, 2014

Show 2 comments Hide comments harding and 1 other commented on an outdated diff Oct 1, 2014

Show 7 comments Hide comments harding and 1 other commented on an outdated diff Oct 1, 2014

Show 1 comment Hide comment harding commented on an outdated diff Oct 1, 2014

Show 3 comments Hide comments harding and 1 other commented on an outdated diff Oct 1, 2014

Show 4 comments Hide comments harding and 2 others commented on an outdated diff Oct 1, 2014

Show 4 comments Hide comments harding and 2 others commented on an outdated diff Oct 1, 2014

Show 6 comments Hide comments harding and 1 other commented on an outdated diff Oct 1, 2014

harding commented on the diff Oct 1, 2014

harding commented Oct 1, 2014

saivann commented Oct 1, 2014

harding commented on the diff Oct 2, 2014

luke-jr added some commits Oct 2, 2014

luke-jr commented Oct 2, 2014

Show 2 comments Hide comments harding and 1 other commented on an outdated diff Oct 2, 2014

luke-jr commented Oct 2, 2014

saivann commented Oct 2, 2014

luke-jr commented Oct 2, 2014

Show 1 comment Hide comment harding commented on an outdated diff Oct 2, 2014

harding commented on the diff Oct 2, 2014

harding commented Oct 2, 2014

saivann commented Oct 2, 2014

harding added a commit to harding/bitcoin.org that referenced this pull request Oct 3, 2014

harding referenced this pull request in luke-jr/bitcoin.org Oct 3, 2014

luke-jr added a commit to luke-jr/bitcoin.org that referenced this pull request Oct 3, 2014

luke-jr added some commits Oct 1, 2014

luke-jr commented Oct 3, 2014

harding commented Oct 3, 2014

saivann merged commit f85c631 into bitcoin-dot-org:master Oct 3, 2014

This was referenced Oct 4, 2014

harding and 1 other commented on an outdated diff Oct 1, 2014

harding and 1 other commented on an outdated diff Oct 1, 2014

harding and 1 other commented on an outdated diff Oct 1, 2014

harding and 2 others commented on an outdated diff Oct 1, 2014

harding and 1 other commented on an outdated diff Oct 1, 2014

harding and 1 other commented on an outdated diff Oct 1, 2014

harding commented on an outdated diff Oct 1, 2014

harding and 1 other commented on an outdated diff Oct 1, 2014

harding and 2 others commented on an outdated diff Oct 1, 2014

harding and 2 others commented on an outdated diff Oct 1, 2014

harding and 1 other commented on an outdated diff Oct 1, 2014

harding and 1 other commented on an outdated diff Oct 2, 2014

harding commented on an outdated diff Oct 2, 2014

saivann merged commit `f85c631` into bitcoin-dot-org:master Oct 3, 2014