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.

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#).
  • A possible sub-section would be an FAQ.

• 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

• 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

Component Interactions Notes:

• Points under Modals are organized in sections within the Modals page, 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