Usage Example Styling Guide (#138)

Author: SimonRhook

src/content/docs/Products/SplashKit/Splashkit Website/Tutorials Documentation/02-Tutorial-Style-Guide.mdx

@@ -390,5 +390,9 @@ write_line(name + "'s quest is: " + quest)
 Use callouts (also known as [Asides](https://starlight.astro.build/guides/components/#asides)) to
 highlight tips or important notes.
 
-:::tip[Make the page interesting] These can help to direct the reader to any extra info, and help to
-add more colour to your tutorial guide. :::
+:::tip[Make the page interesting]
+
+These can help to direct the reader to any extra info, and help to add more colour to your tutorial
+guide.
+
+:::

src/content/docs/Products/SplashKit/Splashkit Website/Usage Examples/01-overview.mdx

@@ -15,9 +15,9 @@ Usage examples demonstrate a specific Splashkit function within a simple, small
 to keep the program minimal while clearly showing how the function works.
 
 For instance, the `write_line` example on the Splashkit site found
-[here](https://splashkit.io/api/terminal/#write-line-5), clicking on the `See Code Example` shows
-how the `write_line` function works, with a brief title of the program, program code, and a
-screenshot of the output.
+[here](https://splashkit.io/api/terminal/#write-line), clicking on the `See Code Example` shows how
+the `write_line` function works, with a brief title of the program, program code, and a screenshot
+of the output.
 
 The following pages cover all the steps to create, submit, and review usage examples for the
 Splashkit website.
@@ -46,16 +46,28 @@ Splashkit website.
    - **C#**: Provide both a version using top-level statements and an Object-Oriented (OOP) version.
    - **Python**: Write a Python version that is straightforward and reflects the same functionality.
 
-4. **Capture Output Screenshots and Write Explanations**:  
-   Run each program version, take screenshots of the output, and write a brief explanation for each
-   language version. Describe what the program does, which function it demonstrates, and highlight
-   any important details.
+4. **Create a Title for the example**:
 
-5. **Add Files to the Correct Folder in the SplashKit Repository**:  
-   Organize your files in the appropriate folders within the SplashKit repository. Ensure file names
-   and directory paths are consistent with SplashKit’s structure.
+   - Think of a title that describes the overall functionality of the program.
+   - Be creative with this title. It should not be the name of the function, or use the word
+     "Example".
 
-6. **Submit a Pull Request for Usage Examples**:  
+5. **Capture Output of Program**: Run the program in any of the languages to capture the details of
+   the program running. You might do this with a screenshot, screen recording converted to a GIF, or
+   an audio recording.
+
+   | Output Format    | Accepted File Type | Example of when to use                                    |
+   | ---------------- | ------------------ | --------------------------------------------------------- |
+   | Screenshots      | `.png` file        | Simple program without any user inputs or animations.     |
+   | Screen Recording | `.gif` file        | The program has user inputs or animations to demonstrate. |
+   | Audio Recording  | `.webm` file       | The program include audio sounds.                         |
+
+6. **Add Files to the Correct Folder in the SplashKit Repository**:
+
+   - Copy your files into the appropriate folder within the `splashkit.io-starlight` repository.
+   - Ensure file names and directory paths are consistent with SplashKit’s structure.
+
+7. **Submit a Pull Request for Usage Examples**:  
    Follow the steps in the
    [Pull Requests for Usage Examples guide](/products/splashkit/splashkit-website/usage-examples/03-usage-pull-request).
    Use the provided PR template, describe your example clearly, and attach explanations and
@@ -80,8 +92,7 @@ Splashkit website.
   href="/products/splashkit/splashkit-website/usage-examples/04-usage-peer-review"
 />
 <LinkCard
-  title="Updating Usage Examples"
-  description="How to update usage examples for the Splashkit website, including the necessary
-   steps and guidelines."
-  href="/products/splashkit/splashkit-website/usage-examples/05-updating-examples"
+  title="Style Guide for Usage Examples"
+  description="General rules to follow when creating usage examples."
+  href="/products/splashkit/splashkit-website/usage-examples/05-usage-example-style-guide"
 />

src/content/docs/Products/SplashKit/Splashkit Website/Usage Examples/02-creating-usage-examples.mdx

@@ -15,10 +15,10 @@ This guide explains how to create a usage example for the Splashkit website.
 ### What are Usage Examples?
 
 Usage examples demonstrate a specific Splashkit function within a simple, small program. The goal is
-to keep the program minimal while clearly showing how the function works.
+to keep the program minimal while clearly showing how the function works or how it can be utilised.
 
 For instance, the `write_line` example on the Splashkit site shows how the `write_line` function
-works, with a brief explanation, program code, and a screenshot of the output.
+works, with a relevant title, program code, and a file showing the program output.
 
 ![example showing on site for write line function](./images/usageexample.png)
 
@@ -43,8 +43,8 @@ In a separate pull request, to add to existing examples:
 
    The planner board has numerous usage example suggestions for various functions, however you are
    welcomed and encouraged to come up with your own creative ideas for these. Scroll through the
-   [Developer Documentation](https://splashkit.io/api/) to find various functions you could use for
-   the usage example, when coming up with an idea, make sure to also check to see if anyone else has
+   [API Documentation](https://splashkit.io/api/) to find various functions you could use for the
+   usage example, when coming up with an idea, make sure to also check to see if anyone else has
    already done it.
 
    The goal is to create **one usage example per function** in the SplashKit library. Building out

src/content/docs/Products/SplashKit/Splashkit Website/Usage Examples/03-usage-pull-request.mdx

@@ -43,7 +43,7 @@ Describe the example and what it demonstrates.
 Splashkit Function: `function_name`
 
 # Files Included
-- [ ] Title and explanation (.txt)
+- [ ] Relevant title for the example (.txt)
 - [ ] C++ code (SplashKit)
 - [ ] C++ code (Beyond SplashKit - In separate pull request)
 - [ ] C# code (Top-Level statements)

src/content/docs/Products/SplashKit/Splashkit Website/Usage Examples/04-usage-peer-review.mdx

@@ -14,21 +14,109 @@ will need to follow the steps for reviewing usage examples.
 
 When reviewing an example, follow these steps:
 
-1. Test each code file on your machine.
-2. Check the structure and functionality of the code in each language.
-3. Review the preview on the website.
+### 1. Test the code
 
-If there are any issues comment on the pull request with the necessary changes. Once those changes
-are made, then use the following template as your comment in the pull request.
+Compile/run each code file on your machine.
 
-```shell
+- Are there any errors?
+- Are there any warnings?
+- Does the program run as expected?
+
+### 2. Analyse the effectiveness
+
+Consider the function being demonstrated and how it might be used by a SplashKit user.
+
+- Does the code example demonstrate the usefulness of the function?
+- Or, do the code example give more insight into how the function works?
+- Is the example simple enough for an SIT102 or SIT771 student to follow, while still being an
+  interesting example?
+
+### 3. Compare and analyse the code
+
+Check the structure and functionality of the code in each language.
+
+- Does the sequence of code match for all code files?
+- Do the code comments match across all code files?
+- Does the code follow the
+  [style guide](/products/splashkit/splashkit-website/usage-examples/05-usage-example-style-guide)
+  requirements?
+- Is the Object Oriented C# code using the Object Oriented format where possible/relevant?
+- Is the python code using the correct function names? (These function names will often differ from
+  other languages due to python not handling function overloads)
+
+### 4. Test in localhost
+
+Check the example displays correctly in your local development environment.
+
+- Does the website build successfully with `npm run build`?
+- Does the example display under the correct function when previewing the website with
+  `npm run preview`?
+- Is the correct function highlighted in the example code?
+
+### 5. Request changes
+
+Add your review comments on the pull request on GitHub.
+
+- Add comments for individual lines, or groups of lines in the code files. This helps the original
+  contributor to understand exactly what the issue is related to.
+- Use professional language, and be polite but assertive.
+- Include the correct version of code where relevant, or any suggested improvements.
+- Ask questions if something is confusing or unclear.
+
+:::note
+
+**First Peer Review:**
+
+- It is _very unlikely_ that you will approve a pull request on first review without any changes.
+- We all miss things in our own code, which is why peer reviews are so important.
+
+**Second Peer Review:**
+
+- This review is more likely to be able to be approved without changes being requested.
+- However, it is important to check that the first reviewer did not miss anything that _should have
+  been found_ in the first review.
+- You might also have experience that allows you to consider other aspects that the first reviewer
+  would not have noticed.
+
+:::
+
+### 6. Continue discussion about changes on the pull request
+
+Check for replies on the pull request from the original contributor.
+
+- These comments might be requesting more information about your suggested changes, so it is
+  important to respond quickly.
+- Discussions may include some debate on the best way forward. Be open to the ideas suggested by the
+  other person, and include evidence to back up your reasoning.
+- If needed, either the reviewer or the original contributor can reach out to your Mentor to help
+  decide what the outcome should be.
+- Check for a comment from the original contributor that the requested changes have been made.
+
+### 7. Review the pull request again
+
+Repeat steps 1 - 4 above.
+
+- It is important to review the pull request thoroughly to ensure that the changes have not caused
+  other issues.
+- You may notice other issues once changes have been made. This is okay, and is part of the
+  development process.
+- Ensure that the pull request will be able to be merged upstream to the live site before you
+  approve it.
+
+### 8. Approve the pull request
+
+Once all the requested changes have been made, approve the pull request using the following template
+in the comment of the approving review:
+
+```plaintext
 # Peer Review
 
 I've reviewed the ...
 
-# Checks
+## Checks
+
 - [ ] All required files are present.
-  - [ ] Title and explanation (.txt)
+  - [ ] Example Title (.txt)
   - [ ] C++ code (SplashKit)
   - [ ] C# code (top-level statements)
   - [ ] C# code (Object-Oriented Programming)
@@ -39,12 +127,18 @@ I've reviewed the ...
 - [ ] Code clearly demonstrates the function.
 - [ ] All versions maintain the same structure and comments.
 
-# Tests done
+## Code Tests done
+
 - [ ] C++ SplashKit code ran correctly.
 - [ ] C++ Beyond SplashKit code ran correctly.
 - [ ] C# top level code ran correctly.
 - [ ] C# OOP code ran correctly.
 - [ ] Python code ran correctly.
+
+## Website Tests done
+
+- [ ] npm run build
+- [ ] npm run preview
 ```
 
 Ensure while doing peer reviews that you also follow the