Open JFWooten4 opened 1 month ago
This is a fantastic idea! I think I remember there being a similar issue (or maybe a few of them?) being created at some point, but they've (obviously) not been taken up yet. Really good ideas in here!
Edit: Here's the issue I was thinking of, although this one here is far more thorough and complete.
@JFWooten4 Great idea, thanks for sharing
What problem does your feature solve?
GitHub content, community interactions, and actual code all coalesce into our collective documentation.[^max_tx]
Accordingly, we can create stellar docs detailing our knowledge, collectively describing how the network functions. π©βπ»
Today's nonexistent contribution style guide leaves one person voicing opinions with a centralized SDF reviewer.[^code_rev] This isn't fair for the reviewer's time, the contributor's confusion, or the browser's sanity. Moreover, a clear style guide can help developers independently build in line with our shared vision. π
What would you like to see? π
A style guide under theACONTRIBUTING.md
page.CONTRIBUTING.md
file which explicitly details general collaboration styles.We respectfully submit that an independent Contributing page outside of
stellar-docs/README.md
would significantly further community collaboration since:Ultimately, might these guideposts steer us all towards a newfound documentation experience, without unnecessary missteps?[^conflict]
What alternatives are there?
We could leave the community reviewers up to their own devices when manually looking over pull requests. This is what happens now, and contributions often get merged despite conflicting syntax. π€ I'm not saying that you must follow the guidelines 100% or else get rejected; just proposing that they exist in the first place when someone does want to follow the standard practice or clean up existing work.
We could use Stella, stricter
prettier
logic, or some other AI to automate the formatting amendments. π€Do nothing and leave my conscious unbearably restless, likely causing nightmares. π»
[^max_tx]: See, e.g., the discussion of maximum network throughput getting fragmented between Discord chats, SDF posts, and GitHub PRs rather than actual ecosystem proposals, dedicated GitHub discussions, or public developer meetings.
[^code_rev]: See, e.g., isolated discussions on example orders, cross-referencing, code spacing.
[^conflict]: See, e.g., one page which starts off using two space indents (most common throughout docs) and then transitions to using tab indention. These conflicts should be fairly simple to rectify using existing tools. It would also be nice to document when, where, and how to insert
README.mdx
files, in an effort to create a readable repository.