Guides Overhaul (Conceptualization)

[Mewyk]

Description

Overview

What is the purpose of this conceptualization? The guides are essentially the key informative area of the documentation for NetCord (C# library for DIscord's Api). That being said, proposing an overhaul that isn't just semantical, but has a greater audience reach is essential for growth. Thus, I am drafting this concept (plan) to extend the reach of the guides in a universal sense.

More thoughts and Q&A about the concept from me to come later as I update the concept.

Global Notes: - Notes/Warnings/Information will be abundant, though abridged enough to get to the point while always linking to points of reference and/or a final link pointing to a more direct informational source of the main point. - There should be a sub-section dedicated for an FAQ. - Another sub-section would be more clarification (plus expanded information, or rather a non-abridged write up in general) for all of the global notes/warnings/information bits that require such.

Structure

Important Note: This concept is an active work in progress and subject to change drastically. Everyone is welcome to provide feedback and suggestions that can be discussed as needed.

• Introduction

  • A basic single page introduction, which is meant to act as a more detailed table of contents after the brief introduction. Essentially it will provide an accordion like collapsable menu, with a short breakdown/overview of each section in a sentence or two.
  • At the end, will lead the user to choose either the QuickStart or the getting started (for those not used to Discord Api and/or C#).
  • Potentially integrating a minimal "kitchen sink" type of app (Which I would call Kuba's Cakes) as the "QuickStart/Getting Started" overall app.

• QuickStart

  • Giving the minimal information needed to get someone started with the library.
  • This section assumes the developer is already familiar with modern C# practices as well as knowledge of .NET 8 and newer.
  • Provides minimal code snippets that demonstrate how simple and quick it is to get NetCord up and running.

Getting Started Note: This section should cover all of the existing "Basic Concepts" from the current guides, as in order to get someone started with the library, we should certainly be covering the basics.

• Refactoring Getting Started to cover all the basics is suggested.
• Potentially following the structure similar to Discord's Api Documentation - Getting Started
• Afterword is essentially a conclusion with links to: Guides (The categories with a quick sentence explaining it), Tutorials, Samples
• Will need to address the differences between embeds and components v2, more so utilizing components v2 and a quick note or something to clarify the push away from embeds.

• Getting Started
  • Installation
  • Project setup
  • Creating a Bot
  • Running your Bot
  • Messages & Components
  • Commands & Interactions
  • Afterword

Commands Notes:

• Points under introduction are organized in sections within the introduction page, not their own sub-pages.
• Shared functionality explanations being either per command sub-category or as its own "shared" sub-category is still to be determined.
• Introduction's overview section will provide short summaries of the different types, anchor linking to each.

• Commands
  • Introduction
    • Overview
    • What are app commands?
    • What are text commands?
    • Use cases and recommendations
  • Slash Commands
  • User Commands
  • Message Commands
  • Text/Prefix Commands

Components v2 Notes:

• Currently just a raw structure based on the Discord Api docs. Expect this to change and/or expanded on.

• Components v2
  • Layout Components
  • Content Components
  • Interactive Component

Interactions (Components) Notes:

• This category is currently pending due to the recent change in the api introducing components v2 (which has given ideas to re-organize once more)
• Modal parts are organized in sections within the Modals page itself, not their own sub-pages.

• Component Interactions

  • Message Components
    • Action Row
    • Button
    • Select Menu
  • Modals
    • Text Input

• Webhooks

  • Introduction (Overview)
  • Managing Webhooks
  • Sending Webhook Messages

• Voice

  • Introduction
    • Overview
    • Setting Up (Prerequisites)
  • Audio Playback
    • Playing Audio
    • Playback Control
  • Audio Recording
    • Capturing Audio
    • Processing Audio
  • Voice Channel Management
    • Joining Channels
    • Leaving Channels
    • Switching Channels
  • Voice State Management
    • Voice State Updates
    • Speaker Detection
  • Voice Region Management
    • Setting Voice Region
  • Voice Connection Management
    • Establishing Connection
    • Maintaining Connection
    • Error Handling

Modernization Notes:

• This category focuses on providing a brief rundown on the various modernization practices that will help improve the overall development experience and results.
• Essentially, this category is not directly related to NetCord, but inherently is.
• "Project Planning" category is pending purpose and its name. Will likely be changed.

• Modernization
  • Project Planning
  • .NET Generic Hosts
  • Configuration (appsettings.json)
  • Dependency Injection

Discord Integrations Notes:

• Remains pending a name change, as it could still be improved.
• Points under Direct Messages are organized in sections within that page, not their own sub-pages.

• Discord Integrations
  • Connecting
  • Events
    • Gateway
    • Channel
    • Guild
    • Message
    • Presence
    • Typing
    • User
    • Voice
    • Interaction
    • Webhook
  • Http Interactions
  • Sharding
    • Channels
    • Creating
    • Updating
    • Deleting
  • Messages
    • Listening for Messages (MessageCreate tends to throw people off)
    • Handling Messages
    • Direct Messages (Creating/Editing/Deleting)
    • Reactions
    • Pins
    • Emotes (Not sure where this should go)
  • Guild Management
    • Creating/Updating/Deleting
    • Channels
    • Roles
    • Users (Includes Banning)
    • Integrations
  • Users
    • Getting User Information
    • Updating User Profile
  • Roles
    • Creating & Deleting
    • Assigning & Updating
  • Permissions
    • Guild
    • Channel

---

• Additional Functionality (Not organized yet)
  • Custom Modules
  • Custom Contexts