Developer Guide on bitcoin.org: writers/reviewers needed

[harding]

I already figured that you mean applications based on bitcoind's RCP API, or an API of other components that your firm is busy developing.

There is no firm.  This is volunteer-written documentation for the entire Bitcoin community.  However, we do have to start somewhere---and I can't think of anywhere better to start than Bitcoin Core.

I'm sorry if I confused you.  Thanks again for your comments!

[piotr_n]

Sorry, it's said in OP that the foundation might pay $2000/month for this project, so it made me thinking that they were driving this spec.

Anyway, I believe it is important to have it clearly distinguished where an actual protocol ends and where a specific software implementation starts.
The doc, although a nice piece of work, unfortunately mixes it all up.

To be more specific.
Lets go to the section "P2P Network / Peer Discovery" - what would I, a developer, expect to find there?
I would expect to find a technical information about how the peers discover each other in the p2p network.
But what I find is a description of what command line switches I can use when launching "Bitcoin Core" (that's a new name for me, BTW - it was always bitcond or bitcoin-qt).
Then somewhere at the end, there is finally a mention of the actual protocol, but pretty laconic and also quite useless (at least ATM), because it still requires you to go to the wiki to learn about the actual format of the payload of the addr message.
Then you have a few sections where you talk strictly about the p2p protocol... until a reader reaches the "Misbehaving Nodes", where his lecture suddenly gets switched back to bitcoind's user manual, and that's without even any indication of the fact.
I think it's pretty confusing. I mean, it doesn't confuse me (you don't need to be sorry), but it will definitely confuse people who read it to study bitcoin.

There is a huge difference between a bitcoin protocol and a specific implementation of a software, but I don't see the doc being even aware of this fact.
If you want to make this spec right, I would advise to try not mixing up these two things.
A reader should be aware all the time whether he is reading about a specific software implementation or about a protocol.
Moreover, it is also important to distinguishing the protocol's must-have hard rules (blockchain validation) and the protocol's may-have soft rules (different address types, the payment protocol, bloom filters, etc). And of course, the command line switches are neither of the two - they are the third kind, a user manual kind.

To wrap up, it is a really nice literature, you obviously put a lot of work into it and it has a potential to become a useful dev spec, but..
IMHO you should restructure it, because now it mixes up things from completely different domains, without mentioning it to the reader. That is not good for a developer's guide / reference.

[blockgenesis]

Sorry, it's said in OP that the foundation might pay $2000/month for this project, so it made me thinking that they were driving this spec.

Beside supporting the project, the Foundation is uninvolved with decision-making. Most of this money was allocated to translations.

Anyway, I believe it is important to have it clearly distinguished where an actual protocol ends and where a specific software implementation starts.

Agreed, I think we can continue to move toward this goal, although it will never be perfect as the distinction isn't always clear in reality either (Bitcoin Core being "the specification" right now until we possibly have multiple full nodes implementations in the future).

[piotr_n]

although it will never be perfect as the distinction isn't always clear in reality either (Bitcoin Core being "the specification" right now until we possibly have multiple full nodes implementations in the future).

Indeed.
Certainly you cannot say whether e.g. the fact that a banned peer gets un-banned after 24h - is a protocol rule, or a specific implementation.
In fact, entire domains like the "misbehaving nodes" concept or "standard transactions" are implementation specific.
Of course it is important to have it documented, because the bitcoin core handles now like 99,99% of the network, but when developing your own bitcoin node nobody can force you to follow these specific concepts and a development spec should be clear about it.
At the other hand developing your own node you definitely need to follow the p2p spec (at least for the commands you use), and most of all: the blockchain protocol - that's the very core of bitcoin, and still not quite documented.

[super3]

Can someone post a list of the authors to this guide and their bitcoin addresses here?

[harding]

super3:

Greg Sanders and myself (Dave Harding) wrote almost all of the original text. The in-text illustrations were all done by me, I think. Saïvann Carignan (blockgenesis) was managing editor, integrated the text into the website (along with icon development), and generally did the many small necessary things to keep the project on track and productive. I'd call us three the current core docs team (but more people are welcome!).

Mike Hearn brought most of us together, provided a large number of invaluable early reviews, and more ongoing feedback to the degree his busy schedule allowed.  Knowing we had the explicit support of at least one core dev was highly motivating, and I think we're all deeply appreciative that Mike was willing to lend his time to our endeavor.

Tom Geller provided line-level editing of the first-written section of the guide, the Block Chain section, as well as creating the style guide we continue to follow.

Chris Beams has been continually providing reviews, feedback, testing, and suggestions both on the text and the website presentation.

Quite a few other people have contributed, although in ways that are harder to track. For example, Greg and myself used the Bitcoin Wiki extensively for research, and the authors of those articles deserve a huge thanks. We're also incredibly grateful to everyone who reviewed parts of our text for accuracy---even if they didn't find any mistakes.

I hope I haven't forgotten anyone.

As for Bitcoin addresses, Saïvann (blockgenesis) received some docs thank-you donations and has already made arrangements to split them between himself, Greg, and myself once they stop coming in. He's been receiving those donations to the address in his sig, 18XXXQs1vAQGBAZbXKA322r9Zy1nZac2H4.  If you send a tip because of the docs, you really should mention it to him that it was for the docs.

However, speaking only for myself, I think the best contributions we can receive are additional reviews for accuracy and help spreading the word about these docs.

[super3]

super3:

Greg Sanders and myself (Dave Harding) wrote almost all of the original text. The in-text illustrations were all done by me, I think. Saïvann Carignan (blockgenesis) was managing editor, integrated the text into the website (along with icon development), and generally did the many small necessary things to keep the project on track and productive. I'd call us three the current core docs team (but more people are welcome!).

Mike Hearn brought most of us together, provided a large number of invaluable early reviews, and more ongoing feedback to the degree his busy schedule allowed.  Knowing we had the explicit support of at least one core dev was highly motivating, and I think we're all deeply appreciative that Mike was willing to lend his time to our endeavor.

Tom Geller provided line-level editing of the first-written section of the guide, the Block Chain section, as well as creating the style guide we continue to follow.

Chris Beams has been continually providing reviews, feedback, testing, and suggestions both on the text and the website presentation.

Quite a few other people have contributed, although in ways that are harder to track. For example, Greg and myself used the Bitcoin Wiki extensively for research, and the authors of those articles deserve a huge thanks. We're also incredibly grateful to everyone who reviewed parts of our text for accuracy---even if they didn't find any mistakes.

I hope I haven't forgotten anyone.

As for Bitcoin addresses, Saïvann (blockgenesis) received some docs thank-you donations and has already made arrangements to split them between himself, Greg, and myself once they stop coming in. He's been receiving those donations to the address in his sig, 18XXXQs1vAQGBAZbXKA322r9Zy1nZac2H4.  If you send a tip because of the docs, you really should mention it to him that it was for the docs.

However, speaking only for myself, I think the best contributions we can receive are additional reviews for accuracy and help spreading the word about these docs.

Ok I sent some BTC to that address earlier. I'll probably send some more at another time. Thanks for compiling an authors list. Good documentation was something that we have been missing for a while. Glad to finally have something.

I just finished reading through it today. I've been making minor contributions to Bitcoin core since about mid 2013, trying to learn about as much about the protocol as I could. This has really leapfrogged my understanding, and I really appreciate it.

[blockgenesis]

However, speaking only for myself, I think the best contributions we can receive are additional reviews for accuracy and help spreading the word about these docs.

+1, but many thanks to the people who gave some generous tips!

[Summer,69]

how much I still need to learn in order to begin to understand what is at stake!

[instagibbs]

although it will never be perfect as the distinction isn't always clear in reality either (Bitcoin Core being "the specification" right now until we possibly have multiple full nodes implementations in the future).

Indeed.
Certainly you cannot say whether e.g. the fact that a banned peer gets un-banned after 24h - is a protocol rule, or a specific implementation.
In fact, entire domains like the "misbehaving nodes" concept or "standard transactions" are implementation specific.
Of course it is important to have it documented, because the bitcoin core handles now like 99,99% of the network, but when developing your own bitcoin node nobody can force you to follow these specific concepts and a development spec should be clear about it.
At the other hand developing your own node you definitely need to follow the p2p spec (at least for the commands you use), and most of all: the blockchain protocol - that's the very core of bitcoin, and still not quite documented.

Any place that doesn't mention that we are talking about Bitcoin Core vs protocol, please submit an issue or pull request. Much appreciated!

Peer discovery doesn't have to be done any particular way, protocol-wise, but in today's environment we deal with Bitcoin Core. As long as we stress that, I think it's ok. I'd be a little baffled if someone writing a complete alternative full implementation didn't understand the implications.

[HELP.org]

Sorry, it's said in OP that the foundation might pay $2000/month for this project, so it made me thinking that they were driving this spec.

Beside supporting the project, the Foundation is uninvolved with decision-making. Most of this money was allocated to translations.

Many of the same old Bitcoin Foundation members are making the decisions.  They are using some interesting criteria about what gets posted.  I ran across some confusion over the settings in .conf and I tried to have the Wiki entry updated and merged with the current developers guide.  I was met with all kinds of resistance and told that Bitcoin Core should not even be on the site!  Of course Satoshi created the site just for that purpose.

I also tried to get my Bitcoin.me video (https://www.youtube.com/watch?v=t4UYpbRO8nw) placed alongside the other third party vids on the press page.  The guy who runs Bitcoin.org said he liked the video wouldn't add it due to my "attitude."  I have been complaining that the site was hijacked by a small group who shut most people out from these decisions.

Just what we need in Bitcoin, a small group exercising centralized control who acts as the "attitude police" to try to force people to go along with their ideas.    

[instagibbs]

Many of the same old Bitcoin Foundation members are making the decisions.  They are using some interesting criteria about what gets posted.  I ran across some confusion over the settings in .conf and I tried to have the Wiki entry updated and merged with the current developers guide.  I was met with all kinds of resistance and told that Bitcoin Core should not even be on the site!  

The primary guide is indeed *not* about Bitcoin Core config files, but trying to best describe the protocol(trying to avoid the debate about whether p2p networking is a part of the protocol or not. Config files surely aren't).

The guidelines for what is included were designed in the open, and everyone was encouraged to contribute. The fact is that only a few people ended up writing most of it because only a few volunteered.

If you want .config stuff included you're going to have to argue your position on this and not just cry about the Bitcoin Foundation.

[blockgenesis]

Don't feed the trolls.

[HELP.org]

Many of the same old Bitcoin Foundation members are making the decisions.  They are using some interesting criteria about what gets posted.  I ran across some confusion over the settings in .conf and I tried to have the Wiki entry updated and merged with the current developers guide.  I was met with all kinds of resistance and told that Bitcoin Core should not even be on the site!  

The primary guide is indeed *not* about Bitcoin Core config files, but trying to best describe the protocol(trying to avoid the debate about whether p2p networking is a part of the protocol or not. Config files surely aren't).

The guidelines for what is included were designed in the open, and everyone was encouraged to contribute. The fact is that only a few people ended up writing most of it because only a few volunteered.

If you want .config stuff included you're going to have to argue your position on this and not just cry about the Bitcoin Foundation.

Yes, the site was hijacked from its original purpose which was the site for the Bitcoin Core project.  Because it has good SEO it is now being used for other purposes.

as for the config file info the commands are already there in the developers guide for the most part.  The config file information for end users is on the wiki but it is outdated.  I wanted to move the wiki entry, update it, and combine it with the information that is already in the developers guide because it all goes together and bitcoin.org is kept up to date as far as the command line items.  Because the Wiki is outdated and information is now being posted at bitcoin.org you have 2 sets of (sometimes) conflicting information.  I suggested the stuff be updated and moved to bitcoin.org and I was ready to do it.  then Luke-Jr started with a bunch of nonsense and started claiming the site was not for Bitcoin Core and that info should be moved off the site.

After that argument Luke-Jr and Saivann told me my video was good but it was not going to be added because of my "attitude."  They want to control what I say and do on other issues in exchange for posting the video I developed.  the content should be posted on merit, not on deals struck with those who got the site from Satoshi. Of course whoever owns the site can do what they want with it but I object to the claim that it is "community" developed.

Basically, they are pushing people away so they can control things for their own purposes.  I have seen several people in the past who wanted to participate but they became disenchanted with the way these issues are being handled.  Now you have a tiny group of people running the entire site and dictating its content.  



  

[HELP.org]

Don't feed the trolls.

The bitcoin.org sock puppet speaks.  This is the kind of childish reply you get when you try to do something.

I guess I "trolled" FinCEN when I got the Bitcoin mining decision:
http://www.coindesk.com/fincen-bitcoin-miners-need-not-register-money-transmitters/

I guess I am trolling the community when I had the video made at my expense:
https://www.youtube.com/watch?v=t4UYpbRO8nw

I just hang out and troll all day.

[SlipperySlope]

Don't feed the trolls.

Thanks to you and to the foundation for the Developer Guide.

Most of the conversation is on-topic. Not trollish behavior I believe. Crowdsourced projects need to air their issues, while achieving consensus on their policies.

[HELP.org]

Don't feed the trolls.

Thanks to you and to the foundation for the Developer Guide.

Most of the conversation is on-topic. Not trollish behavior I believe. Crowdsourced projects need to air their issues, while achieving consensus on their policies.

Thanks.  My point is to clear up the confusion.  I provide support to new users who have no idea what is going on and they spend all day communicating with experts so issues are seen differently.  What I see happening is that people are referencing outdated or incomplete Wiki entries and it is creating confusion.  Right now census means 2 or 3 insiders decide everything.  Generally the discussion are abruptly cut off in the middle of a discussion once the 2 or 3 insiders comment and make their decision.   If you argue you are a "troll " who is "wasting their time."

for instance, look at the wiki discussion of Bitcoin addresses:

https://en.bitcoin.it/wiki/Address#Address_balances

several of these statements are confusing and they appear to contain editorial comments mixed in with fact similar to incorrect things always Luke-Jr says.  While you can't read the balance directly off the blockchain it can be calculated contrary to the way the Wiki describes it.  The discussion appears to be associated with luke-Jr's dislike of Blockchain.info so he makes all kinds of statements about Bitcoin addresses to try to make Blockchain.info look bad.

As for address reuse Bitcoin was designed so you can use different addresses for each transactions but some users have a specific purpose for address reuse.  People who claim Bitcoin was "meant" to be used one way or another are really inserting editorial comments and not fact and they treat Bitcoin like a religion.  It is a tool that can be used many different ways and not reusing address may be advisable under some circumstances but you can't make blanket statements like that.

If changes are made to the Wiki the same 2 or 3 people who run both the Wiki and Bitcoin.org deny any changes and keep their personal preference which, in this case, is wrong.  An argument ensued last week involving someone who pointed to the Wiki Bitcoin address definition and took it as fact.  Then you had people pointing to Bitcoin.org and claiming something different based on that description which is completely different.  

Also, several users are interested in changing their bitcoin.conf settings which is why I raised that issue.  The developers often raise the issue that users can change their settings.  the Wiki entry is outdated.  Now the developers (at least Gregory Maxwell) says having users edit the conf file will cause to many tech support issues and they say users should be using command line.  Many users never use command line but they may want to change their setting.  For instance, they may wish to connect only to a specific node to prevent their IP from being captured on sites such as blockchain.info.

I am no longer allowed to discuss this on Github because the one person who makes the decisions banned me from the entire site.  It is apparently the same person holding the sock puppet account who just labeled me a "troll"

[blockgenesis]

I think Bitcoin Core configuration files is OT here, this thread is for developer documentation, not user documentation.

This said, as (repeatedly) stated, no permission is required to update the wiki if it is oudated. If someone wants to do the work of duplicating the content and keeping it up to date on bitcoin.org, all this person have to do is to do all the work and convince other contributors it's a good idea, like any other change.

[HELP.org]

I think Bitcoin Core configuration files is OT here, this thread is for developer documentation, not user documentation.

This said, as (repeatedly) stated, no permission is required to update the wiki if it is oudated. If someone wants to do the work of duplicating the content and keeping it up to date on bitcoin.org, all this person have to do is to do all the work and convince other contributors it's a good idea, like any other change.

The developers guide already lists the command line arguments.  The conf file is a subset of those commands.  Bitcoin.org is also doing a page on running your own node (see https://github.com/bitcoin/bitcoin.org/issues/410).  The page about running your own node was suggested by an insider and  approved by you and Garzik without any argument about posting user documentation.  You are going to need the conf file explanation on that page so my issue was 100% on topic as I see it.  I would suggest putting in with the command line arguments in the developer's guide and linking to it from the "Running your own node page."  maybe you can explain more why this "off-topic."

All the information is already within, or will be within, bitcoin.org and there is no purpose in trying to change the Wiki to make a second copy of the same information.  Especially if Luke Jr. is going to come in and deny/change the edits so I would not waste my time trying to do that.  Many people have stopped editing the wiki due to those types of complaints.

The "other contributors" are mostly the 2 or 3 people who go around calling anyone who disagrees with them "trolls."  There is no viable way to reach any sort of community consensus under the current system.  You have already told me the only reason you denied posting the video I had made was because of my "attitude" which is not a legitimate reason.  I am starting to see other similar questions being raised, such as which wallet programs get listed, so I am glad this is bringing everything out into the open.

[harding]

The developers guide already lists the command line arguments.  The conf file is a subset of those commands.

Incorrect.  The developers reference describes Remote Procedure Calls (RPCs) which have nothing to do with the configuration files.

Bitcoin.org is also doing a page on running your own node (see https://github.com/bitcoin/bitcoin.org/issues/410).  ... You are going to need the conf file explanation on that page

Incorrect. I opened the issue proposing that page based on a bitcoin-devel mailing list discussion and, as the issue says, I'm delaying writing that page until there's a setup-free package which allows Bitcoin Core to run as a background service---that means no config file editing will be required.

All the information is already within, or will be within, bitcoin.org and there is no purpose in trying to change the Wiki to make a second copy of the same information.

Incorrect, as described above.

> if Luke Jr. is going to come in and deny/change the edits so I would not waste my time trying to do that.

Scurrilous.  Luke-Jr is the one who suggested you update the Wiki, so he's unlikely to reject a quality contribution.

You have already told me the only reason you denied posting the video I had made was because of my "attitude" which is not a legitimate reason.

I disagree. The video promotes your website (Bitcoin.me) and so your behavior is highly relevant. Based on the calumnious statements you've made in the pull request, issues, email correspondence, and this thread, I would recommend people stay away from you and your website.