stellar / stellar-docs

Documentation for Stellar
https://developers.stellar.org
Apache License 2.0
55 stars 124 forks source link

🎨 Create CONTRIBUTING.md guide for open source contribution #799

Open JFWooten4 opened 1 month ago

JFWooten4 commented 1 month ago

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 the CONTRIBUTING.md page. A 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?

  1. 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.

  2. We could use Stella, stricter prettier logic, or some other AI to automate the formatting amendments. πŸ€–

  3. 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.

ElliotFriend commented 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.

janewang commented 1 month ago

@JFWooten4 Great idea, thanks for sharing