Metadata / Documentation repo for SDK Contributors

[hendrikebbers]

We want to create a new repository containing all the information SDK contributors need. For that we need a good name. Suggestions should be collected here :)

[hendrikebbers]

sdk-contributor-docs

[rwalworth]

Like I mentioned in the meeting this morning, I think in order to come up with a good name, it's important to really hammer out and define all that this repo is meant to contain. SDK contributor information could mean a variety of things and I don't want there to be confusion between what this repo will contain and our official docs repo.

My initial thoughts of items this repo should contain:

• Design information for new HIPs and features. This was the original intent of the repo. These design documents outline the new APIs that should be added to the SDKs, the APIs that should be updated, any internal SDK changes (algorithm changes for example), test plan, TCK tests, and code examples. The documents should follow the template decided on in Add SDK design document template #48.
• Good first issue template. SDKs can use this template to outline good first issues for new developers and contributors to take on in their repos.
• ???

I'm definitely curious to see what others think may be good information to have in this repo and what contributors/developers would find useful to them.

[jwagantall]

So... I asked ChatGPT for an opinion 😬 Based on what we know so far.. this is what it told me

hiero-ledger/sdk-docs – Simple and encompassing, covering both design documentation and templates.
hiero-ledger/sdk-contributions – Broad enough to include all contributions, from design docs to templates like good first issues.
hiero-ledger/sdk-guidelines – Focuses on providing guidance, which fits both design documents and contribution templates.
hiero-ledger/sdk-templates – Directly conveys the idea of templates, including both design templates and contribution templates like good first issues.
hiero-ledger/sdk-plans – Emphasizes the planning aspect, which applies to design documents and templates related to SDK contributions.
hiero-ledger/sdk-specs – Focuses on specifications, which could include both design specs and templates for contributions.

[rwalworth]

Amazing, thanks ChatGPT! My thoughts on the ChatGPT names:

• sdk-docs: we should avoid this in my opinion, as it can be easily confused with the official SDK docs and I don't think this repo should duplicate any information that is already contained there.
• sdk-contributions (or sdk-contributor-docs as @hendrikebbers suggested previously): this could be decent, I'd be curious to know what other docs contributors would want access to that we could store here. Design docs make sense so as contributors know what and how to implement something, but what else could they want to know? And is providing contributors with docs to get started contributing going to be one of the main goals/purposes of this repo?
• sdk-guidelines: this could be decent as well, as it captures what I think one of the main points of the repo which would be describing how and why the SDKs should implement their features.
• sdk-templates: I'm not sure this fits, as the repo will contain more than just templates.
• sdk-plans: it captures the essence of planning out features and HIP implementations, as well as potentially any other additions we'd want to make (or to get contributions and ideas for future versions of the SDKs (v3, v4, etc)). I think I may something like sdk-proposals more, it's in the same vein as this but I think better captures the idea that anybody can propose SDK modifications. However, we may want to store docs here that aren't necessarily proposals.
• sdk-specs: this would work well for just holding design docs, but if it holds any other additional information about the SDKs, it wouldn't work as well

[hendrikebbers]

That is great! I like sdk-guidelines the most.

[exploreriii]

I agree with @rwalworth " it's important to really hammer out and define all that this repo is meant to contain. SDK contributor information could mean a variety of things and I don't want there to be confusion between what this repo will contain and our official docs repo." At the same time, its early in the process and some things will not be predictable.

My feedback:
sdk-docs: -- I would be initially confused, too ambiguous.

sdk-contributions -- I would be initially confused because it is very similar to awesome contributions that makes me think its about showcasing sdk contributions. If that's the goal in mind, this would be a good title perhaps as: sdk-awesome-contributions.

sdk-contributor-docs -- I like this because it is clearly about contributing and probably mostly about code. Most clearly aligned with use case to provide technical information and guidance to sdk contributors. Some ideas - it could point towards the different sdks, mini tutorials on getting started, meetings for technical matters, big picture/goal overview, big timeline work in progress updates. I think I would definitely not look here for python sdk specifics, but I may look here if I don't find all in python sdk, need guidance or if I want to explore other avenues.

sdk-guidelines -- this one is good but perhaps too narrow. Not as clear as sdk-contributor-docs but can be a good title if general guidance is preferred. I hesitate that this narrows focus and creates too much of a top down heavy approach, the word guidelines suggests there are clearer rules in place which have already gone through some review and discussion process. Maybe the repo should be broader than just guidelines.

sdk-templates: -- seems duplicate, perhaps being very close to examples that some of the sdks already have, or overly informational without the community feel. Developers can be sliced in two here.

sdk-plans -- this one is ok but gives it less of a code vibe.

sdk-proposals -- I like this one if there are genuine proposals, such as HIPS. I think this makes sense and the title invites collaboration. Also is a good fit because it is clearly not about a specific sdk, so it is clear it is about the general sdks.

sdk-specs -- unsure if there is sufficient use case for this, seems very targeted at this early stage of the project.

My opinion:
sdk-contributor-docs -- I think has good benefit from the perspective of lowering the barrier to entry for new devs IF there is a use case to add training/high level information and focus in that area. This, however, seems more difficult to pull off because you need to be more advanced in the HIP proposal process to then start writing intro documentation/etc.

sdk-proposals -- I think this has the highest benefit from the perspective of a HIP focused discussion. Proposals is more open than plans, inviting discussions and work. From this, you can then create sdk-contributor-docs. <-- favourite

an intermediary could be:
sdk-contributor -- I think this could support both general standards, intros and HIPs, but unsure if that provides the best environment for resolution of the two areas that differ in scope and time.

[rwalworth]

Thanks for the insights @exploreriii ! I agree with you on pretty much all your feedback. Maybe we can combine a couple of these into one to broaden the scope more directly, something like sdk-proposal-and-contributor-docs?

[jwagantall]

I like sdk-contributor-docs . I am also in favor of a longer name to include the essence of what we are hosting if people don't mind the long name.
Let me know if we can come up with a winner and if you guys need my help creating this.

[SimiHunjan]

I also agree that it is important to define what kinds of documents are going to be hosted in the repo so that we can define a good name for it that is inclusive of all the items.

I generally like sdk-contributor-docs.

[exploreriii]

Seems we are getting closer to aligning.
I prefer sdk-proposal-and-contributor-docs: its probably a good idea to keep the scope on the broader side.
I like sdk-contributor-docs: but is more limited, if there will be HIP discussions, this doesn't feel it fits 100%. But a good outcome.

[hendrikebbers]

I like sdk-contributor-docs. sdk-proposal-and-contributor-docs is too long.

[rwalworth]

I really like the sense of invitation to submit ideas and proposals for SDK features that sdk-proposal-and-contributor-docs brings compared to sdk-contributor-docs, but I understand it's a bit long-winded. To throw two more potential names into the ring to try and bridge the gap between the two "finalists" (these will be my last ones):

• sdk-collaboration-docs: I think "collaboration" does a great job at encompassing all we may look for this repo to do and hold. I think "collaboration" implies that sense of invitation to submit new features and designs and have discussions, and also the teamwork and shared efforts by any and all contributors in improving the SDKs. Keeping it broad with "collaboration" means we won't by limited by the repo name for anything we may want to add to it at any point.
• sdk-collaboration-hub: very much in the same vein as sdk-collaboration-docs but "hub" gives it a more central and welcoming feel. The clarity that this is a docs-only repo gets lost in the name, but anyone could notice upon investigation there's no code in the repo. But also if we end up wanting to keep code samples/snippets in this repo, not having "docs" in the name would be great.

[hendrikebbers]

I like hub :)

[exploreriii]

hub has a nice ring

[hendrikebbers]

We did a vote on the SDK Community call:

• sdk-collaboration-docs: 5
• sdk-collaboration-hub: 5
• sdk-contributor-doc: 3
• sdk-contributor-hub: 4
• sdk-proposal-and-contributor-docs: 0
• sdk-proposal-and-contributor-hub: 0

2nd Round:

• sdk-collaboration-docs: 3
• sdk-collaboration-hub: 6

[jwagantall]

@hendrikebbers
I have added hiero-ledger/governance#178
Let me know if I am doing this right, is my first repo creation using the config 😬