Skip to content

Commit

Permalink
Address sci's comments
Browse files Browse the repository at this point in the history
  • Loading branch information
ChampionAsh5357 committed Oct 7, 2023
1 parent 9e59978 commit 7f5169e
Showing 1 changed file with 22 additions and 10 deletions.
32 changes: 22 additions & 10 deletions src/pages/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,15 @@ npm install
npm run start
```

## An Overview
## Principles

This documentation is a guide to help a modder understand and implement a given concept from Minecraft or NeoForged.

This documentation is NOT meant as a tutorial, allowing a modder to copy-paste the examples. If you are looking for a tutorial, there are plenty of videos and pages, which are not linked here, that you can use and follow along with.
This documentation is **not** meant as a tutorial, allowing a modder to copy-paste the examples. If you are looking for a tutorial, there are plenty of videos and pages, which are not linked here, that you can use and follow along with.

This documentation is also NOT meant as documentation for a class. Providing a description of an element is unavoidable when writing a guide; however, if you would like to document a class, you should contribute to [Parchment for Minecraft][parchment] or [NeoForge for NeoForged][neo].
This documentation is also **not** meant as documentation for a class. Providing a description of an element is unavoidable when writing a guide; however, if you would like to document a class, you should contribute to [Parchment for Minecraft][parchment] or [NeoForge for NeoForged][neo].

Final, this documentation is NOT meant to explain Java concepts. This documentation is intended for people who already has a solid basis in Java. If a Java concept needs to be explained to better understand the concept (such as JVM Descriptors for Access Transformers), a link should be provided to the original resource. Otherwise, if you are unfamiliar with Java, there are plenty of online resources to learn from:
Final, this documentation is **not** meant to explain Java concepts. This documentation is intended for people who already has a solid basis in Java. If a Java concept needs to be explained to better understand the concept (such as JVM Descriptors for Access Transformers), a link should be provided to the original resource. Otherwise, if you are unfamiliar with Java, there are plenty of online resources to learn from:

* [JetBrains Academy][jetbrains]
* [Codeacademy][codeacademy]
Expand All @@ -36,7 +36,9 @@ If you need to refer to other concepts, the relevant page should be linked along

## Examples

Code examples should generally be pseudocode-like objects meant to enhance the understanding of a modder. When implementing a method, it is usually specific to the desired goal a modder is trying to achieve. As a guide, this documentation aims to be somewhat agnostic to a modder's specific goal, instead covering the general use case.
Code examples should generally be pseudocode-like objects meant to enhance the understanding of a modder. For this documentation, pseudocode-like refers to code blocks written in the structure and syntax of the desired language with comments used as placeholders for specific logic that the modder may choose to implement themselves. The code blocks do not necessarily need to be compilable, but each line should have valid syntax and structure of the desired language.

When implementing a method, it is usually specific to the desired goal a modder is trying to achieve. As a guide, this documentation aims to be somewhat agnostic to a modder's specific goal, instead covering the general use case.

Let's say we are using a method called `#applyDiscount` to take some value off the current price. Not everyone will implement the same logic within the method. So, the pseudocode can leave a comment mentioning what to do instead:

Expand Down Expand Up @@ -101,11 +103,11 @@ Titles are defined using up to six hashtags (`#`) to define each section. Titles

### Diction

Spelling, grammar, and syntax should follow those in American English. Avoid using contractions in sentences; use two separate words ('is not' instead of 'isn't'). Additionally, avoid using pronouns when possible, unless you need to directly refer to the reader.
Spelling, grammar, and syntax should follow those in American English. Avoid using contractions in sentences; use two separate words ('is not' instead of 'isn't'). Additionally, avoid using pronouns (e.g. I, me, you) when possible, unless you need to directly refer to the reader. Demonstratives (e.g. this, that, its) should be used sparingly to avoid confusing the reader. Prefer using the actual object or noun being referred to.

### Paragraphs

Paragraphs should be a continuous block, separated by a newline. Paragraphs should NOT have each sentence be on a new line.
Paragraphs should be a continuous block, separated by a newline. Paragraphs should **not** have each sentence be on a new line.

```md
This is my first paragraph. See how the next sentence is on the same line? You can use word wrapping in your editor to stop the line from going off the screen.
Expand All @@ -122,18 +124,28 @@ When indenting lines, use four spaces instead of tabs. Most markdown features re
* Four Spaces In
```

### Importance

Emphasizing words should be done using **bold** or _italics_. Please use two asterisks (`**`) for bold and an underscore (`_`) for italics to make the separation in Markdown more distinct.

```md
This is a **bolded** word.

This is an _italicized_ word.
```

### Code References

When referencing elements outside of code blocks, they should be surrounded with backticks (`` ` ``). Classes should use their simple name. Methods and fields should specify the class name followed by a `#`. If the class name is implied, the method or field can simply be prefixed with `#`. Inner classes should specify the name of the outer class followed by a `$`.
When referencing elements outside of code blocks, they should be surrounded with backticks (`` ` ``). Classes should use their simple name. Methods and fields should specify the class name followed by a `#`. If the class name is implied, the method or field can simply be prefixed with `#`. Inner classes should specify the name of the outer class followed by a `.`.

```md
<!-- Classes -->
`MyClass`
`MyClass$InnerClass`
`MyClass.InnerClass`

<!-- Method and Fields -->
`MyClass#foo`
`MyClass$InnerClass#bar`
`MyClass.InnerClass#bar`
`#SOME_CONSTANT`
```

Expand Down

1 comment on commit 7f5169e

@neoforged-pages-deployments
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deploying with Cloudflare Pages

Name Result
Last commit: 7f5169e536e7cffb897a568d2af35b9d793d0f7a
Status: ✅ Deploy successful!
Preview URL: https://f70fc6de.neoforged-docs-previews.pages.dev
PR Preview URL: https://pr-14.neoforged-docs-previews.pages.dev

Please sign in to comment.