Topic: Developer Guide on bitcoin.org: writers/reviewers needed - page 2. (Read 7781 times)

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.

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!

OK - so it's for "applications".
Now I would have asked "what kind of applications?" if not for the fact that 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.
As an opposite to the actual (software independent) bitcoin protocol applications, as I perceive such through the proto described on the wiki.

So currently it is not a "Bitcoin Developer Reference", but rather a manual for bitcond's RPC API, right?
In such case, I have no critical comments, except maybe for the title of this doc, which I find a bit misleading, to say the least.

You ought to at least make it clear that it is a guide for a specific software API, not so much for Bitcoin as the universal bitcoin protocol.
Otherwise some more experienced devs could blame you of advertising a misleading message about what Bitcoin actually is  

Yup, it's always good to move forward and think of new improvement. We can't have everything on v0.1 .

Also, I think that's a good reason why it made sense to focus on bringing new content (walkthrough and explanations) rather than duplicating existing tables on the Wiki (and link to them instead). But at some point I agree that having all this content in a single place can indeed be a useful step forward.

piotr_n:

Our audience description says that we're focusing on application developers, which (in my mind) means that we prioritize writing documentation for developers who will use libraries or Bitcoin Core RPCs for the underlying network communication.

Once we've covered the topics application developers need to know, I'm happy to move on to topics library developers or core re-implementors need to know.

As for opcodes, we describe all the opcodes used in standard transactions here: https://bitcoin.org/en/developer-reference#op-codes

As for cross-reference linking, we use it extensively---there are over 2,000 links in the Guide and Reference.  Just hover your mouse over a paragraph to see all of the internal links appear in blue.  You can further hover your mouse over a term to get a brief description, and then click on it to go to the full description.

We really did put a lot of work into trying to design the docs to be useful for developers at all stages, from Bitcoin neophyte to core dev.  Given more time (or more volunteers!) we'll be able to fulfill our core mission and expand the docs to cover more and more parts of Bitcoin.

Thanks for your comments!

I think I did check everything and really comparing both of your pages, to these two:
https://en.bitcoin.it/wiki/Protocol_specification
https://en.bitcoin.it/wiki/Script
.. I would not envy a guy who has to build a bitcoin software, basing only on your spec.

But OK, I understand that it isn't complete.

Still, if I may add, most of all you need a nice & clean table with all the network messages linking to their descriptions (with sub-tables describing the payload of each type).
And the same for the script - I don't see a table with script opcodes in your spec.
That's the two references I've used the most - nothing else matters that much.

You can have some more epic descriptions, but they should rather be there as an additional help.
So only if anyone doesn't understand what an opcode does (by its name or short desc), he clicks a link and goes there.

Hi, piortr_n.

Did you checkout both the guide and the reference pages?  The guide is aimed at new developers who need to learn how Bitcoin works.  The reference is aimed at the developers who know how the general system works but need, as you say, tables and short explanations (which we've put all on one page for easy in-browser Ctrl-f searching).

• Guide: https://bitcoin.org/en/developer-guide
• Reference: https://bitcoin.org/en/developer-reference

Both are linked to from the main page, which also links to other useful resources: https://bitcoin.org/en/developer-documentation

We'll be adding more content over the next few monhs, so check back often!  Thanks!

Fascinating lecture.
But you cannot seriously think that this is more useful for a dev than the old wiki.
Or can you?
Well, IMHO it isn't - devs need tables and short explanations, not epic descriptions.
It looks good to be released as a book, though.

Not saying that this is a bad piece - only that it is too long to read, as for dev purposes.
Bitcoin isn't that complicated, nor we seek adventures in its documentation.

This is a grade A piece of work. Donated 0.1 BTC to your address.

Now that I have figured it out with help of bitcointalk members, i might add this myself.

A quick update on the project:

More reviews and feedback on the pull request are very welcome so we can get this merged:
https://github.com/bitcoin/bitcoin.org/pull/393

This pull request will be merged on May 24th and hopefully will be accurate as much as possible. Reporting any inaccuracy / mistake on the pull request is very appreciated.

Notes about where to contribute to the current effort from the bitcoin-development mailing list:

I've only just skimmed the new docs but I'm impressed.  Great job.  I'm looking forward to reading it more closely.

Thank you.

Can some please explain the procedure of signing a transaction with multiple inputs?

Hi,

We could use a little advice about what's relevant to wallet authors when it comes to choosing which inputs to select for making a new payment.  We described three options:

* A merge avoidance algorithm makes it harder for outsiders looking at block chain data to figure out how many satoshis the receiver has earned, spent, and saved.

* A last-in-first-out (LIFO) algorithm spends newly acquired satoshis while there's still double spend risk, possibly pushing that risk on to others. This can be good for the receiver's balance sheet but possibly bad for their reputation.

* A first-in-first-out (FIFO) algorithm spends the oldest satoshis first, which can help ensure that the receiver's payments always confirm

We were thinking about cutting out FIFO because it doesn't seem very useful (except for being reliable and easy to implement).  We were further discussing whether we should cut out LIFO---which might be useful for some applications---in order to emphesize the privacy benefits of merge avoidance.

However, none of us writers/editors have any practical experience here, so we would appreciate some developer feedback about what you need to know.  Here's a direct link to the input-selection section and our GitHub discussion of the issue.

A quick trace of Electrum's source code (which I happend to have handy) made it seem like it used FIFO.

Thanks, -Dave

Hi,

The payment processing section (including BIP70 payment requests) has been added to the devguide.  Comments and suggestions are welcome on the pull request.

(Please comment there even though the pull request is closed.  Every comment posted will be read and replied to.)

Thanks to Saïvann's late-night efforts, you can read the new section in nicely-formatted HTML on the demo site.

General questions or comments should be sent here, the mailing list, or submitted as an issue.

Thanks!, -Dave

Edit:  After reading through the Bitcoin Core source code for an embarrassingly long time, I figured out that this paragraph from BIP70,


means to do this:


before doing this:


Thanks to everyone who read my previous post.

Agreed, no server-side scripting for now.

The website is purely static and for security reasons I think it should stay that way. If there is a third party commenting platform that lets us just drop something in via Javascript, I think that'd be OK but not if we need to run some kind of php/ruby thing on the bitcoin.org server itself.

As for working on the API reference page, I wish I could. Hopefully I have enough knowledge to share after I learned more and I will certainly try to help when I'm at that point.

'User contributed notes' are user comments underneath each section.
Basically, where users can submit section related remarks, pitfalls, example code snippets etc. (that maybe can be voted up, down or away).