chore: Update contribution guidelines (#93)

Co-authored-by: Simon (Darkside) Jackson <[email protected]>

CONTRIBUTING.md

@@ -17,7 +17,7 @@ Breaking these rules can result in your contribution being rejected.
 
 For further details for guidance and advice when contributing to the MonoGame Framework Documentation / API repository, please see the official guide:
 
-### [MonoGame Documentation official contributing guide](https://docs.monogame.net/articles/contributing)
+### [MonoGame Documentation official contributing guide](./articles/contributing.md)
 
 ## License
 

README.md

@@ -33,7 +33,7 @@ With your environment setup properly, the following explains how to build from s
   `dotnet docfx docfx.json --serve`
 
 > [!NOTE]
-> Docfx hosting does not support hot reload, so to refresh the hosted site you will need to stop the agent (ctrl-c) and run the above command again to refresh pages
+> Docfx hosting does not support hot reload, so to refresh the hosted site you will need to run `docfx docfx.json` in a separate terminal or stop and rerun the agent (ctrl-c)
 
 ## Document styling
 
@@ -53,7 +53,7 @@ The use of DocFX with the updated MonoGame docs site has afforded the use of som
 
   [DocFX Markdown style guide](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet#alerts)
 
-As an example of a document written using the above notes, please refer to the [HowTo: Create a Render Target tutorial](https://github.com/MonoGame/docs.monogame.github.io/blob/feature/docsmigration/articles/monogame/howto/graphics/HowTo_Create_a_RenderTarget.md)
+As an example of a document written using the above notes, please refer to the [HowTo: Create a Render Target tutorial](./articles/getting_to_know/howto/graphics/HowTo_Create_a_RenderTarget.md)
 
 > [!TIP]
 > No additional text is needed at the bottom of document pages as the licenses and requirements are automatically added by the DocFX build system

articles/contributing.md

@@ -1,126 +1,116 @@
 ---
-title: Contributing guidelines
-description: The following rules must be observed at all times when contributing documentation to the MonoGame project.
+title: Contributing Guidelines
+description: Instructions on how to contribute to the documentation of the MonoGame Framework
 ---
 
-# General Rules
-
-The following rules must be observed at all times when contributing documentation to the MonoGame project.
-
-- Write in a neutral, technical tone.
-- Avoid humor, personal opinions, and colloquial language.
-- **Never** plagiarize any documentation from another source.
-- Do not use automatic documentation tools as they are ineffective.
-
-Breaking these rules can result in your contribution being rejected.
-
-## Getting Started
-
-You can create and edit documentation right from the web browser without needing to install Git or ever leave the GitHub site.
-
-- [Fork the MonoGame repo](https://help.github.com/articles/fork-a-repo/).
-- [Create a new branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) from `develop` and make your changes only in that branch.
-- [Create a new file](https://help.github.com/articles/creating-new-files/) or [edit an existing one](https://help.github.com/articles/editing-files-in-your-repository/) using the GitHub markup editor.
-- [Submit pull requests](https://help.github.com/articles/creating-a-pull-request/) early and often to merge your documentation changes.
+# Contributing to MonoGame Documentation
 
-## Generate the output before submission
+Thank you for choosing to contribute to the MonoGame project! This page provides guidance on how you can help to improve the documentation for MonoGame.   
 
-The `MonoGame.GitHub.io` site has the ability to generate the documentation website locally so that you can verify how the documentation renders `BEFORE` submission, we recommend all contributors validate what is written as it is rendered on the website to help the reviewers checking the PR request.
+# Getting Started
 
-> [!TIP]
-> If possible, include a screenshot in your PR showing the rendered output.  Recommended, but not mandatory.
-
-See the following sections for more details on generating the relevant website pages:
+> [!NOTE]
+> If you are new to making contributions to open source projects, it is recommended to understand the following concepts before submitting your contribution:   
+> 
+> - [How to fork a repo](https://help.github.com/articles/fork-a-repo/).
+> - [Creating a new branch for your fork](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) from `main`.
+> - [Creating a new file](https://help.github.com/articles/creating-new-files/) or [editing an existing one](https://help.github.com/articles/editing-files-in-your-repository/) using the GitHub markup editor.
+> - [How to submit your contributions for review through a pull request](https://help.github.com/articles/creating-a-pull-request/).
 
-- [Generating the Documentation website](#generating-the-documentation-website)
-- [Generating the API Documentation](#generating-the-api-documentation)
+## Articles and API References
 
-## Style Guide
+The MonoGame documentation contains two types of documents: articles and API references.
 
-Review the following expectations before contributing any documentation.
+Articles include manuals, guides and tutorials on how to use the MonoGame Framework to create games.
 
-### Manuals, Guides, and Tutorials
+API references provide detailed explanation of each class and method found in the MonoGame Framework. The documentation is written in the [C# XML format](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments) and is inline to the MonoGame source code. 
 
-TODO!
+## Generating the Documentation Site
 
-#### Generating the Documentation website
+The pages for articles and API references are hosted on a documentation site that is generated using [DocFX](https://dotnet.github.io/docfx/).
 
-To generate the documentation site locally, simply:
+To generate a local copy of the documentation site:
 
-1. Clone the [MonoGame.GitHub.io](https://github.com/MonoGame/MonoGame.github.io) repository.
-2. Follow the instructions in the site readme for preparing your environment and generating the documentation.
-3. Use the `npm run articles` command to finally generate the site to only check the documentation updates (although it may be easier to simply run `npm run dev` to generate everything)
-4. Browse the running site from `http://localhost:xxxx`
+1. Fork the [docs.monogame.github.io](https://github.com/MonoGame/docs.monogame.github.io) repository.
+2. Follow the instructions in the site's [readme](https://github.com/MonoGame/docs.monogame.github.io?tab=readme-ov-file#docsmonogamegithubio) for preparing your environment and generating the documentation.
+3. If you intend to make contributions to the API References, then run `git submodule update --init --recursive` command to update the `external/MonoGame` submodule to your local fork.
+4. Use the `dotnet docfx docfx.json --serve` command to serve a local copy of the documentation site.
+5. Browse the running site from `http://localhost:xxxx`.
 
-Check the `Documentation Hub` pages for your changes and include screenshots of the pages when you are ready to submit. (Optional, but recommended)
+> [!TIP]
+> Verify your changes in your local documentation site before submitting a pull request with said changes. It is recommended to include screenshots of the pages in the pull request to help reviewers confirm these changes.
 
-### API Reference
+# General Rules
 
-The API reference documentation is a big part of the documentation effort for MonoGame.  The documentation is written in the [C# XML format](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments) and is inline to the MonoGame source code. The final web pages with API documentation are generated using [DocFX]([DocFX - static documentation generator | DocFX website](https://dotnet.github.io/docfx/)).
+The following rules **must** be observed at all times when contributing documentation to the MonoGame project.
 
-#### Generating the API documentation
+- Write in a neutral, technical tone.
+- Avoid humor, personal opinions, and colloquial language.
+- **Never** plagiarize any documentation from another source.
+- Do not use automatic documentation tools as they are ineffective.
 
-To generate the docs locally, simply:
+> [!WARNING]
+> Breaking these rules can result in your contribution being rejected.
 
-1. Clone the [MonoGame.GitHub.io](https://github.com/MonoGame/MonoGame.github.io) repository.
-2. In the `External` folder, update the `MonoGame` submodule to your own **Fork/Branch**.
-3. Follow the instructions in the site readme for preparing your environment and generating the documentation.
-4. Use the `npm run dev` command to finally generate the site to view both API and general documentation pages.
-5. Browse the running site from `http://localhost:xxxx`
+# General Style Guide
 
-Check the `API Reference` pages for your changes and include screenshots of the pages when you are ready to submit. (Optional, but recommended)
+Because there are many contributors to the MonoGame documentation, it can be difficult to maintain a coherent writing style throughout the documentation site. In addition to the [General Rules](#general-rules), this style guide serves to inform contributors of the conventions needed to maintain this writing style. So please review the following expectations before contributing any documentation.
 
-#### Every Word Should Contain Value
+## Every Word Should Contain Value
 
 Every word in the reference documentation should provide information beyond the API itself.  Documentation that only rehashes or rephrases what is already apparent in the class, method, parameter, or property name has zero value and wastes time for both the writer and reader.
 
-#### The First Sentence Is the Most Important
+## The First Sentence Is the Most Important
 
 There is no guarantee that the reader will read beyond the first sentence of the reference documentation.  This is why that first sentence is the most important and should convey the most key piece of information.  Take your time to write the most concise and clear first sentence possible.  This helps users tremendously and goes a long way towards having great documentation.
 
-#### Surface Information Hidden in the Code
+## Surface Information Hidden in the Code
 
 Being inline with the code allows you to easily look for critical information within it that the user might not know from looking at the API alone.  Take your time to explore inner method calls and platform specific sections of the code.  The time to write the documentation is once you feel you fully understand the code you are documenting.  If you don't feel you understand the code then leave the documentation for someone else to write.
 
-#### Focus on what adds value to the consumer
+## Focus on What Adds Value to the Consumer
 
 Limit documentation to public methods and functions unless there is a specific reason to include internal methods, while documenting internals helps with readability of the code, it provides limited use to consumers of the MonoGame Framework.
 
-#### Documentation Is Referenced Not Read
+## Documentation Is Referenced Not Read
 
 Remember that the user is searching for an answer for a specific question.  It is your job to predict these questions and provide them clear answers.
 
-#### Descriptions should add value and understanding
+## Descriptions Should Add Value and Understanding
 
 Describing a thing by naming the thing does not help the developer to understand what the concept is that you are describing, for example:
 
 > "The Genre class provides information about a genre"
 
 Which does not help someone reading the documentation if they do not know what a `Genre` is.  Be descriptive and improve the readers understanding for what something is and WHY it is.
 
-#### XML Tag guidance
+# API Reference Style Guide
+
+In addition to the [General Style Guide](#general-style-guide), please consider the following conventions used for code associated with the API reference docs. 
+
+## XML Tag Guidance
 
 By default, the standard [Microsoft recommendations](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) should be used for filling in XML tags for each class, method and property.
 
 With a few points to call out:
 
-#### See / CRef should be used whenever an API reference is used in the documentation
+### `<see>` and `<cref/>` should be used whenever an API reference is used in the documentation
 
 To ensure that API documentation is linked to whichever reference is used, `<see>` and `<cref/>` references should be used, this helps users navigate the methods, especially when looking up initializers or use of a property or method.
 
-#### Avoid self referencing `<cref/>` unless it provides value
+### Avoid self referencing `<cref/>` unless it provides value
 
 `<cref/>` blocks are there to add links and create references to other classes, functions and methods that help inform the developer for what those concepts are.  Adding a `<cref/>` for the same class or property you are describing just creates a circular reference that does not add value.
 
 References to other methods or properties in the same class is fine, just avoid self if possible.
 
-#### Use descriptors in `<see/>` & `<cref/>` statements for better readability
+### Use descriptors in `<see/>` and `<cref/>` statements for better readability
 
 By default, a `<cref/>` or `<see/>` reference will use only the type you are referencing when rendered to the user, e.g. `<cref="Album.Genre"/>` will render as `Genre`.
 
 Instead, use the descriptor in the style to render what you actually mean, for example: `<cref="Album.Genre">Album.Genre</cref>` which will always render as `Album.Genre` which is much clearer, it is the same for `<see/>` tags.
 
-#### 120 Width comments for easy reading
+### 120 width comments for easy reading
 
 Comments should be limited to **120** width, with overflow moving to the next line to make reading easier, for example:
 
@@ -135,7 +125,7 @@ and the y component uses 6 bits.
 > If the `cref` description would cause the line to exceed the 120 recommendation, this is generally ok, so long as the rendered line does not exceed the limit.
 > THe limit however, is more of a guideline than a hard rule, so common sense should be applied to keep the limit near 120 characters.
 
-#### Use the packed multi-line stype with surrounding tags
+### Use the packed multi-line style with surrounding tags
 
 To keep the documentation packed and readable, each parameter should be contained to a single line, for example:
 
@@ -148,7 +138,7 @@ Creates a new instance of Bgr565.
 <param name="z">The z component</param>
 ```
 
-#### Interface documentation
+## Interface Documentation
 
 If documentation is already provided by an interface or inherited class, then the `<inheritdoc />` tag should be used.  Critically, **DO NOT** duplicate documentation as it increases maintenance later, for example:
 
@@ -162,7 +152,7 @@ public void Dispose()
 
 This applies to all derived elements within a class, property or method.
 
-#### Inherited properties
+## Inherited Properties
 
 Where a property or type is already documented in an `enum` or `static`, to avoid duplication the `<inheritdoc cref=""/>` style should be used, for example:
 
@@ -185,7 +175,7 @@ Where a property or type is already documented in an `enum` or `static`, to avoi
         public static readonly VertexDeclaration VertexDeclaration;
 ```
 
-#### Protected methods requiring documentation by the linter
+## Protected Methods Requiring Documentation by the Linter
 
 By default, we do not document Finalizers or other protected methods, the recommendation is to apply an empty `<summary />` tag to suppress the warnings raised by the linter, for example: