Stellar docs code snippet

[apaldiwal]

Link the bounty file

https://github.com/tyvdh/stellar-quest-bounties/blob/main/bounties/level-1/stellar-docs-code-snippet.md

Mark your progress

• 🔵  Started working
• 🟢  Ready for review
• 🟣  Review completed

Stellar Documentation

Name	Language	Award	Paid
Glossary
Clawback	Java (Pending)	150 XLM
Clawback	Python (Pending)	150 XLM
Claimable Balance	Python (Merged)	150 XLM	✅

Horizon API Reference

Name	Language	Award	Paid
Retrieve Fee Stats	Python (Pending)	50 XLM
List Claimable Balances	Java (Pending)	50 XLM
Ledgers
Retrieve a Ledger	Go (Pending)	50 XLM
Retrieve a Ledger's Transactions	Go (Pending)	50 XLM
Retrieve a Ledger's Operations	Go (Pending)	50 XLM
Retrieve a Ledger's Payments	Go (Pending)	50 XLM
Retrieve a Ledger's Effects	Go (Pending)	50 XLM
List All Ledgers	Go (Pending)	50 XLM
Transactions
Retrieve a Transaction	Go (Pending)	50 XLM
Retrieve a Transaction's Operations	Go (Pending)	50 XLM
Retrieve a Transaction's Effects	Go (Pending)	50 XLM
List All Transactions	Go (Pending)	50 XLM
Operations
Retrieve an Operation	Go (Pending)	50 XLM
Retrieve an Operation's Effects	Go (Pending)	50 XLM
List All Operations	Go (Pending)	50 XLM
List All Payments	Go (Pending)	50 XLM
Accounts
List All Accounts	Go (Pending)	50 XLM
Retrieve an Account	Go (Pending)	50 XLM
Retrieve an Account's Transactions	Go (Pending)	50 XLM
Retrieve an Account's Operations	Go (Pending)	50 XLM
Retrieve an Account's Payments	Go (Pending)	50 XLM
Retrieve an Account's Effects	Go (Pending)	50 XLM
Retrieve an Account's Offers	Go (Pending)	50 XLM
Retrieve an Account's Trades	Go (Pending)	50 XLM
Retrieve an Account's Data	Go (Pending)	50 XLM
Offers
Retrieve an Offer	Go (Pending)	50 XLM
List All Offers	Go (Pending)	50 XLM
Trades
List All Trades	Go (Pending)	50 XLM
Assets
List All Assets	Go (Pending)	50 XLM
Claimable Balances
List Claimable Balances	Go (Pending)	50 XLM
Retrieve a Claimable Balance	Go (Pending)	50 XLM
Retrieve Transactions for a Claimable Balance	Go (Pending)	50 XLM
Retrieve Operations for a Claimable Balance	Go (Pending)	50 XLM
Order Books
Retrieve an Order Book	Go (Pending)	50 XLM
Paths
List Strict Send Payment Paths	Go (Pending)	50 XLM
List Strict Receive Payment Paths	Go (Pending)	50 XLM
Trade Aggregations
List Trade Aggregations	Go (Pending)	50 XLM
Fee Stats
Retrieve Fee Stats	Go (Pending)	50 XLM

[apaldiwal]

I'm not sure how to categorize the code into unique function blocks. What do you think?

[kalepail]

Here's how it's currently being done.
#68

[kalepail]

Oh looks like you had an Issue here: #49. Probably best to either re-open that one or else copy that data here and just begin to comment as PRs to the docs repo gets merged. Were they all merged?

[apaldiwal]

Oh looks like you had an Issue here: #49. Probably best to either re-open that one or else copy that data here and just begin to comment as PRs to the docs repo gets merged. Were they all merged?

No, just this one. I can have a new column in the table where I can report the status of each PR. Does that work?

[kalepail]

Yeah probably 🤔 No need to open a new issue for each merge I don't think. Just need to track the progress as it happens in the one Issue. It's a bit of a unique bounty but worth thinking about how best to keep track with it. Probably should still mark as 🟣 on that as the review is technically done or being done and as far as this bounty repo is concerned all that's left is to get you paid!

[apaldiwal]

Yeah probably 🤔 No need to open a new issue for each merge I don't think. Just need to track the progress as it happens in the one Issue. It's a bit of a unique bounty but worth thinking about how best to keep track with it. Probably should still mark as 🟣 on that as the review is technically done or being done and as far as this bounty repo is concerned all that's left is to get you paid!

Done! I know you explained it earlier, but I'm still a little confused about how to count the unique code blocks in each example. It's a bit of a gray area really because there's a lot of ambiguity in how you split the code into functional blocks.

[kalepail]

I agree 100%. Would love to hear your thoughts around this. Is per file better than per block? What do you think it's worth? I'd really love to ensure I'm being generous and fair while also being somewhat algorithmic/predictable about it.

[apaldiwal]

I agree 100%. Would love to hear your thoughts around this. Is per file better than per block? What do you think it's worth? I'd really love to ensure I'm being generous and fair while also being somewhat algorithmic/predictable about it.

I feel 'per file' is a better option for code involving operations because you can't just pick and choose a block of code from the example and submit a PR in the repo. You have to fully incorporate the example in code while ensuring syntactical consistency with the existing examples. For example, https://developers.stellar.org/docs/glossary/claimable-balance/

On the other hand, for code involving API Reference we can use 'per block' to award bounties because we only have to deal with one functional aspect at a time. For example, https://developers.stellar.org/api/aggregations/fee-stats/single/

Honestly, I am really indecisive when it comes to picking numbers for a bounty. So, I'm okay with whatever you end up deciding. :)

[ralphilius]

Yeah probably 🤔 No need to open a new issue for each merge I don't think. Just need to track the progress as it happens in the one Issue. It's a bit of a unique bounty but worth thinking about how best to keep track with it. Probably should still mark as 🟣 on that as the review is technically done or being done and as far as this bounty repo is concerned all that's left is to get you paid!

Maybe we could link from the original PR so that we can have PR status in the review issue (e.g. #68) ?

I think tThis type of bounty is typical if we want some organization to sponsor a bounty to maintain their documentation as well.

[kalepail]

Yeah probably 🤔 No need to open a new issue for each merge I don't think. Just need to track the progress as it happens in the one Issue. It's a bit of a unique bounty but worth thinking about how best to keep track with it. Probably should still mark as 🟣 on that as the review is technically done or being done and as far as this bounty repo is concerned all that's left is to get you paid!

Maybe we could link from the original PR so that we can have PR status in the review issue (e.g. #68) ?

I think tThis type of bounty is typical if we want some organization to sponsor a bounty to maintain their documentation as well.

Has he not done that?

Or are you referring to something else?

[kalepail]

@apaldiwal I just updated your original tables with my proposed award amounts. Do they seem fair? No is a correct answer, I want this to generously reflect the work you put in such to properly incentivize future work along these lines so think for others and not just for yourself.

If anyone else would like to chime in here feel free.
cc: @rahimklaber @ralphilius @Kanaye @Smephite @ElliotFriend @hanseartic

[ElliotFriend]

Why the difference between the two? It's been hard to keep up with all the discussions, so it's possible (rather, likely) that I've missed something.

At first glance 50 seems a bit low, but I have no real reasoning behind that, just kind of a "gut feeling."

[rahimklaber]

To me it seems that part of the problem is making it fair for people of multiple experience levels. If you are experienced the rewards will probably a lot for you, since you will be able to write examples quickly. But if you are newer it will take you more time. I guess this is fair though, experienced people should be paid more.

For now I think 50 xlm per block is fair.

Also, I feel like I rambled and maybe missed the point, but I think what @apaldiwal will get is fair. I would maybe even give more for the Java examples since Java can be so combersome to work with, but thats just me.

[kalepail]

Why the difference between the two? It's been hard to keep up with all the discussions, so it's possible (rather, likely) that I've missed something.

Good question. If you look at the code blocks for the code being committed I see three distinct blocks of code in the changed file. Undoubtedly the first block is much more complex than others but I see a pretty distinct collection of blocks. So that was my logic.

It's a tricky balance between fair and algorithmic so folks have some sense of what to expect and it's not up to how generous I'm feeling that day.

We can certainly bump to 100 XLM per code block as this is a particularly beneficial value add for our docs and does have a cap in that we only need Python examples once per block not everyone on planet earth can write more Python code snippet examples. So generous but limited.

Seem fair?