Let's create a foundation for competition among BTS developers

[xeroc]

I think sphinx is way for powerful than gitbook .. but moving from rest to markdown syntax using pandoc is easy to ... if you are not happy with the current docs ..

sphinx can compile to PDF and ODF as well, btw
and it can create flow charts in svg using gravphizs
See:
https://raw.githubusercontent.com/BitSharesEurope/docs.bitshares.eu/7b641f495fd5a6e3247785f9631b074750bd8359/source/bitshares/user/transactions-proposed.rst
image: http://docs.bitshares.eu/bitshares/user/transactions-proposed.html

[jakub]

This is what Ethereum currently has:
https://ethereum.gitbooks.io/frontier-guide/content/

Very simple but appears to be quite practical.
It has a search utility which is another important feature of a good tutorial.

Nice find .. i can definitely improve our stuff on that!

they are using gitbooks, we used as well for the past BitAssets WP IRRC

@cass
Was it any good? Anybody complained about it?

[cass]

This is what Ethereum currently has:
https://ethereum.gitbooks.io/frontier-guide/content/

Very simple but appears to be quite practical.
It has a search utility which is another important feature of a good tutorial.

Nice find .. i can definitely improve our stuff on that!

they are using gitbooks, we used as well for the past BitAssets WP IRRC

[xeroc]

This is what Ethereum currently has:
https://ethereum.gitbooks.io/frontier-guide/content/

Very simple but appears to be quite practical.
It has a search utility which is another important feature of a good tutorial.

Nice find .. i can definitely improve our stuff on that!

[xeroc]

Except for
  "- create working examples of "hello world" smart contracts and operations,"
that is exactly what I am doing already for quite some time

In your worker proposal you state very vaguely:

Lots of Documentation (e.g. docs.bitshares.eu), Whitepapers, BSIPs,

@xeroc , is there any place where I can find what areas you intend to address in the documentation covered by your worker proposal?
And also what areas you definitely don't intend to address?

This would help us greatly in avoiding overlapping.

There is nothing that I do NOT want to have in there .. (except maybe politics) ..

There is also a poll on what I should work on next:
https://bitsharestalk.org/index.php/topic,19967.new.html#new
I tackled some of them already

I know that ideally we would like to have everything united in one place.
However, please be more specific what your plans and capabilities are for the next 2-3 months, as otherwise it's hard for me to specify goals for a person attempting to create a Graphene development tutorial.
Telling him/her "just work with xeroc and fill in whatever you can" is not specific enough IMO.

My aim is to create a tutorial which will enable an experienced C++ developer to code, test and deploy something as complex as BSIP #6
What parts of this know-how will you cover? What areas are you not able to cover?

EDIT: Judging from the poll, it looks to me that your documentation is aimed at those two use-cases:
- how to use BitShares
- how to create third-party apps that interface with BitShares (e.g. mobile wallets, gateways, bridges)
And what you don't seem to cover is anything that introduces changes affecting the BitShares protocol (i.e. requiring hard-forks).
Is it a fair definition of the scope of your docs?

(If so, how does your intention to write "hello world" contracts and operations fit into this?)

I'd like to keep my work more user centric and only document stuff that is useful for integrating with bitshares.

Hence, you are free to design your c++ turorials as you like .. i will only integrate it into the existing structure but we can talk about that detail later on ...

[jakub]

This is what Ethereum currently has:
https://ethereum.gitbooks.io/frontier-guide/content/

Very simple but appears to be quite practical.
It has a search utility which is another important feature of a good tutorial.

[jakub]

I have given some thought to the matter of Graphene tutorial and here are my conclusions:

(1) Our situation is quite similar to Android - we don't need to teach people a new programming language, we only need to teach them how to use a known language in a very specific environment.
In Android's case this familiar programming language is Java, in our case it's C++. When coding natively in Android, you need to be aware of and familiar with the Android Activity Cycle. When coding within Graphene, I guess you need to be aware of being within a blockchain OS.
As we have this nice analogy between Android/Java and Graphene/C++, and Android's tutorials are already mature and rich with comprehensive examples, I propose to make Android's tutorials a quality benchmark we aim to achieve in the long run.

(2) We have these high quality examples:
http://developer.android.com/training/index.html
http://www.vogella.com/tutorials/Android/article.html
http://www.codelearn.org/android-tutorial#tutorial
https://www.objc.io/issues/11-android/android_101_for_ios_developers/

Does anybody know of software tools aimed at creating and maintaining tutorials like the ones listed above?
I know xeroc is using something called ReStructureText for docs.bitshares.eu but it looks a bit rough to me in terms of UX.
Maybe it can be customized with CSS but maybe there are more flexible or more advanced tools?

Also, in the future we might need to have a comments/questions section, as this tutorial does:
http://www.codelearn.org/android-tutorial/android-introduction
So I guess we might need some more complex tool-set than ReStructureText can offer.

EDIT: Please suggest examples of your favorite tutorials so that we can define our expectations a bit better.

[jakub]

Except for
  "- create working examples of "hello world" smart contracts and operations,"
that is exactly what I am doing already for quite some time

In your worker proposal you state very vaguely:

Lots of Documentation (e.g. docs.bitshares.eu), Whitepapers, BSIPs,

@xeroc , is there any place where I can find what areas you intend to address in the documentation covered by your worker proposal?
And also what areas you definitely don't intend to address?

This would help us greatly in avoiding overlapping.

There is nothing that I do NOT want to have in there .. (except maybe politics) ..

There is also a poll on what I should work on next:
https://bitsharestalk.org/index.php/topic,19967.new.html#new
I tackled some of them already

I know that ideally we would like to have everything united in one place.
However, please be more specific what your plans and capabilities are for the next 2-3 months, as otherwise it's hard for me to specify goals for a person attempting to create a Graphene development tutorial.
Telling him/her "just work with xeroc and fill in whatever you can" is not specific enough IMO.

My aim is to create a tutorial which will enable an experienced C++ developer to code, test and deploy something as complex as BSIP #6
What parts of this know-how will you cover? What areas are you not able to cover?

EDIT: Judging from the poll, it looks to me that your documentation is aimed at those two use-cases:
- how to use BitShares
- how to create third-party apps that interface with BitShares (e.g. mobile wallets, gateways, bridges)
And what you don't seem to cover is anything that introduces changes affecting the BitShares protocol (i.e. requiring hard-forks).
Is it a fair definition of the scope of your docs?

(If so, how does your intention to write "hello world" contracts and operations fit into this?)

[xeroc]

Except for
  "- create working examples of "hello world" smart contracts and operations,"
that is exactly what I am doing already for quite some time

In your worker proposal you state very vaguely:

Lots of Documentation (e.g. docs.bitshares.eu), Whitepapers, BSIPs,

@xeroc , is there any place where I can find what areas you intend to address in the documentation covered by your worker proposal?
And also what areas you definitely don't intend to address?

This would help us greatly in avoiding overlapping.

There is nothing that I do NOT want to have in there .. (except maybe politics) ..

There is also a poll on what I should work on next:
https://bitsharestalk.org/index.php/topic,19967.new.html#new
I tackled some of them already

[Empirical1.2]

Hiring some latvian coder from freelancer.com, or some such other generic source will be a waste of time; they will simply not have the expertise to do the job properly even if they do know c++ inside out. Simply put, blockchain programming is an extremely specialised niche within a niche and you must expect to pay a premium to get someone who knows what they are doing.

Moving forward, I suggest you fund CNX to produce a series of competency tests which test candidate programmers for their knowledge of low level, blockchain oriented systems, design methodologies and general c++. CNX would need to be in charge of the hiring process, because they know their systems inside out.

Completely agreed here ...

KenCode seems to have done pretty well sourcing help and expertise for his BitShares mobile wallet project at a competitive price.

https://bitsharestalk.org/index.php/topic,20776.0.html

[cass]

Hiring some latvian coder from freelancer.com, or some such other generic source will be a waste of time; they will simply not have the expertise to do the job properly even if they do know c++ inside out. Simply put, blockchain programming is an extremely specialised niche within a niche and you must expect to pay a premium to get someone who knows what they are doing.

Moving forward, I suggest you fund CNX to produce a series of competency tests which test candidate programmers for their knowledge of low level, blockchain oriented systems, design methodologies and general c++. CNX would need to be in charge of the hiring process, because they know their systems inside out.

Completely agreed here ...

[monsterer]

Hiring some latvian coder from freelancer.com, or some such other generic source will be a waste of time; they will simply not have the expertise to do the job properly even if they do know c++ inside out. Simply put, blockchain programming is an extremely specialised niche within a niche and you must expect to pay a premium to get someone who knows what they are doing.

Moving forward, I suggest you fund CNX to produce a series of competency tests which test candidate programmers for their knowledge of low level, blockchain oriented systems, design methodologies and general c++. CNX would need to be in charge of the hiring process, because they know their systems inside out.

[jakub]

Except for
  "- create working examples of "hello world" smart contracts and operations,"
that is exactly what I am doing already for quite some time

In your worker proposal you state very vaguely:

Lots of Documentation (e.g. docs.bitshares.eu), Whitepapers, BSIPs,

@xeroc , is there any place where I can find what areas you intend to address in the documentation covered by your worker proposal?
And also what areas you definitely don't intend to address?

This would help us greatly in avoiding overlapping.

[pc]

I'm currently working in a full-time contract and am not available for a worker position.

In any case, I wouldn't be the best candidate for the job. I'm only vaguely familiar with the Graphene codebase. Most of my previous work has been on the old client and the fc library, not on the actual Graphene code.

[xeroc]

Before we go searching for talented C++ coders outside of the BitShares community, might it not be wise to inquire as to which of our local bts community talents could be persuaded to put time into such an effort?  @xeroc is already well along in his efforts.  What about @svk?  Might a sufficiently well paid worker proposal be able to persuade some of our highly talented friends to focus on developing this 'foundation'?

If we're going to spend bts for such efforts, if possible I'd prefer to see it go towards people whose reputations and interests are already firmly aligned with the success of BitShares.

Thoughts?

Thanks, I'd love to dig into C++ BUT I am quite sure that it will not be very efficient until I get more experienced with it even though I know the API and parts of the code already.
It may be more cost-efficient to hire an experienced C++/BOOST developer for this.
Also, there is @pc, who is very firm with C++ and already did quite some work for the core base. Why not offer a well-paid job to him? @pc: would you be interested in getting hired again by the blockchain?