🧑🏾‍🎨 Open source contributing foundations

[JFWooten4]

solving #799

@briwylde08 mentioned that "networks tabs you can't use .mdx at the end of the link" - but I'm unfamiliar with the nuances here 🤔

[briwylde08]

Hey! Great job on proposing a contribution guideline section for the docs — this will be really helpful as we encourage more community involvement. I especially like the details around writing code examples, defining Stellar terms, and cross-referencing.

Some general feedback I have is on language in general.

I think the language could be clearer and more neutral to better suit developer documentation. For example, in the Code Examples section, you wrote:

If you're technically inclined, example applications of documented functions can go a long way to further the network's understanding. Writing a quick snippet is an easy way to connect with developers, and the local simulation translates code!

Instead, I’d suggest simplifying it to:

Here's how to write correctly-formatted code blocks in Markdown.

The goal is to make the language more straightforward and focused on practical guidance. I’d also recommend removing language like:

Let's very carefully implicate some of the ethos behind the community in an effort to distill Balancing the World's humanitarian principles into something that's subtly nudging towards an empowering, creative, and inclusive readership tone.

This kind of language is too complex and opinionated for readers who are looking for clear and actionable guidance on contributing. I think we should aim for concise, clear, and direct phrasing to ensure it’s accessible for all contributors.

Again, I think this is a great start and I'm excited to get a contribution guide out there!

[ElliotFriend]

Great start @JFWooten4! As I'm thinking about what needs to be in the contribution guidelines, here are some "sections" that come to mind. You likely already have thought of (most of) these, but I'll just write them out for the sake of collaboration.

• referencing other docs pages (i.e., *.mdx vs non-mdx files, and when to use which)
• code example indentations (i.e., 4 spaces for python, 2 spaces for javascript, etc.) (ideally, we should have that codified in a prettier config or something)
• how to use the custom react components (seems like you've already gotten that ball rolling pretty well)
• how to run the formatting/linting scripts, when/why you should, and if you should commit everything or just the files you're working on.
• handling certain characters to avoid markdown compilation errors (< for example will cause the compilation to fail, and it should be escaped like \<)
• special-case source files for some pages (openapi specs, cli guides, etc.)

Again, great start! Glad to have this in the works!! Thanks again

[JFWooten4]

@ElliotFriend @briwylde08 Thank you both so much for voicing your initial reactions to my very rought draft! 💜 I will implement these thoughts and more in due time, and then circle back. One last thing I was wondering, I noticed¹ that a lot of the pages use [link](./FILENAME.mdx) while a simpler syntax could use [link](FILENAME.mdx)—any opinionated preference on same-dir referencing?

Footnotes

1. This is an outlier example where it references a folder rather than it's README.mdx, but it's most common to see dot-slash introductions from my experience, which I think complicates the editing plaintext interpretation. If you just want to voice a quick reply, perhaps a 👍 for (./FILENAME.mdx) or a 🚀 for (FILENAME.mdx) might suffice? ↩

[JFWooten4]

How do you two feel about simplifying Go type declarations when multiple parameters share the same type?¹²

In the limited context of Go functions, do you have a preference for using entirely explicit typedefs v. inheriting previous?

If it's a binary answer, perhaps a 🎉 for "defining all" (option B) or a ❤️ for "item grouping" (option A)?

Footnotes

1. In Go, you can group parameters of the same type to simplify function signatures: func addLiquidity(source *keypair.Full, maxReserveA, maxReserveB float64) {}³ (option A) ↩

2. Compare behavior to that in Java, whereby you must explicitly declare the type for each parameter, even if they share the same type: public static void addLiquidity(KeyPair source, String maxReserveA, String maxReserveB) {} (option B) ↩

3. Note the maxReserveA does not have a subsequent type defined, since it is assumed that it's a float64 when maxReserveB compiles. ↩

[JFWooten4]

We'll also need to clarify heading trailing commas, sectional href names, and cutoff lengths.