docs: credit class, project, and batch tutorial

[ryanchristo]

Description

Closes: #1339 / Ref: regen-network/rnd-dev-team#1731

This pull request adds a tutorial for credit class, project, and batch creation and management.

Preview: https://deploy-preview-1965--regen-ledger-docs.netlify.app/tutorials/user/credit-class-project-batch-management.html

---

Author Checklist

All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.

I have...

• included the correct type prefix in the PR title
• added ! to the type prefix if API or client breaking change
• targeted the correct branch (see PR Targeting)
• provided a link to the relevant issue or specification
• followed the guidelines for building modules
• included the necessary unit and integration tests
• added a changelog entry to CHANGELOG.md
• included comments for documenting Go code
• updated the relevant documentation or specification
• reviewed "Files changed" and left comments if necessary
• confirmed all CI checks have passed

Reviewers Checklist

All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.

I have...

• confirmed the correct type prefix in the PR title
• confirmed ! in the type prefix if API or client breaking change
• confirmed all author checklist items have been addressed
• reviewed state machine logic
• reviewed API design and naming
• reviewed documentation is accurate
• reviewed tests and test coverage
• manually tested (if applicable)

[ryanchristo]

cc @clevinson @blushi I think this is ready for an initial review when you get a chance.

[clevinson]

Thanks for putting this together @ryanchristo. Feels great to finally see this kind of documentation coming to the ledger docs.

As a high level point of feedback, I think it would read easier if the details of IRIs / data resolving / etc. were in a separate section / page from the credit class administration. If someone is coming to this tutorial with the expectation to read about credit class creation, I think it'd be nice to be able to easily jump to the meat of the "Credit Class" section, even if it does mean they need to go back to read up on how metadata works later. Part of me wonders if this would read more easily if it were 4 separate tutorial pages (I think vuepress will automatically render <- and -> navigation links at hte bottom of a page to navigate between tutorials) for each section.

Something like (each on a separate page):

• Overview of "Credit origination tutorial" and table of contents
• page on data management / RDF datasets / data hosting expectations
• credit class creation & updates (+ credit class prerequisites)
• project creation & updates
• batch creation & updates

Does vuepress allow for this sort of multi-pages nested within one tutorial?

[clevinson]

Suggested change

You can now view your new credit class, project, and batch using a version of [Regen Marketplace](https://dev.app.regen.network/) connected to Redwood Testnet. You also might notice there is not much information on the pages but you have some new abilities. Check out [Regen Network Guidebook](https://guides.regen.network/guides/regen-marketplace) to learn about managing credit classes, projects, and batches using the Regen Marketplace application.

You can now view your new credit class, project, and batch using the [Regen Marketplace -Testnet App](https://dev.app.regen.network/) connected to Redwood Testnet. You also might notice there is not much information on the pages but you have some new abilities. Check out [Regen Network Guidebook](https://guides.regen.network/guides/regen-marketplace) to learn about managing credit classes, projects, and batches using the Regen Marketplace application.

[clevinson]

Not sure I understand what is meant by this: "You also might notice there is not much information on the pages but you have some new abilities."

Can you clarify what's meant here?

[ryanchristo]

Non-anchored metadata is not covered in this tutorial. Users would ideally go to the guides for more information about what they can do in the marketplace application.

[ryanchristo]

I didn't make any changes here.

[clevinson]

I still find that phrasing of "you may have some new abilities" kind of confusing. Can you upgrade the wording to be more explicit?

[ryanchristo]

Upgraded 704fb81

[blushi]

great work @ryanchristo

are you going to take care of documenting projects/batches creation/updates from the UI on https://guides.regen.network/ too?
I guess there we should also explain the difference between anchored/unanchored metadata for projects and that unanchored project metadata can only be updated via the UI

[blushi]

best to include the @type here as well and add schema:image too, see generic credit-class.json in regen-network/regen-registry-standards#56

[blushi]

could you add schema:image field too?

[ryanchristo]

Added a0a7b46

[ryanchristo]

As a high level point of feedback, I think it would read easier if the details of IRIs / data resolving / etc. were in a separate section / page from the credit class administration. If someone is coming to this tutorial with the expectation to read about credit class creation, I think it'd be nice to be able to easily jump to the meat of the "Credit Class" section, even if it does mean they need to go back to read up on how metadata works later. Part of me wonders if this would read more easily if it were 4 separate tutorial pages (I think vuepress will automatically render <- and -> navigation links at hte bottom of a page to navigate between tutorials) for each section.

Something like (each on a separate page):

Overview of "Credit origination tutorial" and table of contents
page on data management / RDF datasets / data hosting expectations
credit class creation & updates (+ credit class prerequisites)
project creation & updates
batch creation & updates
Does vuepress allow for this sort of multi-pages nested within one tutorial?

I don't think this is necessary and one concise tutorial page seems like a good starting point to me. If we want to go into any more detail on each section, it would probably make sense to spin out into a separate tutorial that goes into more detail.

I see this tutorial as the high-level overview for credit class, project, and batch creation and management. All the information you need is on one page with links for additional context.

[ryanchristo]

are you going to take care of documenting projects/batches creation/updates from the UI on https://guides.regen.network/ too?

I believe I'll be helping @clevinson and @S4mmyb with the UI tutorial.

[ryanchristo]

@clevinson @blushi I think this is ready for another review. Only open question is the IRI generation endpoint.

[clevinson]

So in general I still think this would flow better with some contextual framing (pulling out the essentials from ecocredit module concepts) and possibly re-ordering or splitting up the sections into multiple pages. But if you'd rather that get take care of in a separate PR, I can try to get to it myself in a follow-up.

I went back through the comments I had previously left and resurfaced the ones that still stood out to me as confusing. Hopefully these lighter suggestions feel like improvements?

[clevinson]

I still think the way this is currently worded is confusing. Particularly the part where you say 'we need to construct "graph" data using JSON-LD format'. I prefer to see a little bit more description here as to what we mean in this context, and thought my suggestion was doing a good job at that. If you didn't like my approach, can you try to give some more context to what is meant by "graph" data inline instead of just linking out to the RDF docs? I think that would be valuable for most developers, as the RDF docs I find notoriously dense, and the one-pager w3c page linked here doesn't give many examples or talk about JSON-LD at all.

If you do try rewording this, I still think linking to this doc (or something similar) could be useful to help explain JSON-LD in the context of RDF: https://www.w3.org/TR/json-ld/#relationship-to-rdf

[clevinson]

I think it'd be valuable to give a little more context to this section and explain to the user what they are supposed to do with these templates.

Something like: "The following templates can be used as a starting point. Users should feel free to add their own fields in additions to the ones here. New fields that are added from other vocabularies should include a reference in the JSON-LD "@context", ideally linking to a published vocabulary (similar to "schema" and "http://schema.org").

[ryanchristo]

Added 704fb81

[clevinson]

I still find that phrasing of "you may have some new abilities" kind of confusing. Can you upgrade the wording to be more explicit?