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.

1. Introduction
   • Package Overview (NetCord, NetCord.Services, NetCord.Hosting)
2. Quick Start
3. Getting Started
   • Installation
   • Creating Your Bot
   • Project Setup
   • Running Your Bot
   • Your First Response
   • Afterword
4. .NET Integration
   • .NET Generic Host
   • Configuration
   • Logging
5. Discord Entities
   • Overview
   • Working with Users
   • Working with Guilds
   • Working with Channels
   • Roles and Permissions
   • Emojis and Stickers
6. Events
   • Overview
   • Intents
   • Gateway Events
   • Webhook Events
7. Components v2
   • Overview
   • Migrating from Embeds
   • Layout Components
   • Content Components
   • Interactive Components
   • Modal Components
8. Commands
   • Overview (links to Services Framework)
   • Slash Commands
   • User Commands
   • Message Commands
   • Text Commands
9. Component Interactions
   • Message Components
   • Modals
10. Services Framework
    • Overview
    • Dependency Injection
    • Type Readers
    • Preconditions
    • Custom Contexts
11. Webhooks
    • Overview
    • Managing Webhooks
    • Sending Messages
12. Voice
    • Overview
    • Connecting to Voice
    • Audio Playback
    • Audio Recording
    • Stream Types
13. Advanced Topics
    • Sharding
    • Caching Strategies
    • Rate Limiting
    • Connection Resilience
14. Deployment
    • Docker
    • Cloud Hosting
15. Troubleshooting
    • Common Issues
    • FAQ

Section Interconnection Map

From Section	Links To	Reason
Introduction	Quick Start, Getting Started	Reader chooses path
Introduction	All sections (overview cards)	Landing page navigation
Quick Start	.NET Integration	References Generic Host setup
Quick Start	Commands, Events	First functional code
Getting Started	.NET Integration	"Learn more about Generic Host"
Getting Started	Discord Entities	"Understanding Users, Guilds, Channels"
Getting Started	Events	"Handling gateway events"
.NET Integration	Getting Started	Back-reference for context
.NET Integration	Services Framework (DI)	DI is core to hosting
.NET Integration	Deployment	Production configuration
Discord Entities	Events	Entities received via events
Discord Entities	Commands	Entities as command parameters
Discord Entities	Permissions (Roles)	Permission checks
Events	Discord Entities	Events contain entities
Events	.NET Integration	Event handlers in Generic Host
Events	Commands	InteractionCreate for commands
Components v2	Sending Messages (Getting Started)	How to send components
Components v2	Component Interactions	Handling component clicks
Components v2	Commands	Responding with components
Commands	Services Framework	Built on NetCord.Services
Commands	Discord Entities	Parameters (User, Role, Channel)
Commands	.NET Integration	UseApplicationCommands()
Commands	Component Interactions	Responding with components
Commands	Preconditions	Permission checks
Component Interactions	Services Framework	Built on NetCord.Services
Component Interactions	Components v2	What triggers interactions
Component Interactions	Commands	Often triggered from command responses
Services Framework	Commands	Implements command services
Services Framework	Component Interactions	Implements interaction services
Services Framework	.NET Integration	DI patterns
Services Framework	Discord Entities	Type Readers parse entities
Webhooks	Discord Entities	Webhook messages
Webhooks	Events (Webhook Events)	Webhook event handling
Voice	Discord Entities	VoiceChannel, VoiceState
Voice	Events	VoiceStateUpdate, VoiceServerUpdate
Voice	.NET Integration	Voice client setup
Advanced Topics	.NET Integration	Sharding uses hosting
Advanced Topics	Events	Rate limiting on events
Deployment	.NET Integration	Production hosting
Deployment	Advanced Topics	Sharding for scale
Troubleshooting	All sections	Common issues per topic

Anchor Sections Per Page

1. Introduction

Anchor	Description
#overview	What is NetCord
#packages	NetCord, NetCord.Services, NetCord.Hosting overview
#features	Feature highlights with links
#choosing-your-path	Quick Start vs Getting Started

2. Quick Start

Anchor	Description
#prerequisites	.NET 8+, IDE, Discord account
#create-bot	Portal setup (brief)
#minimal-code	Bare minimum to run
#whats-next	Links to deeper guides

3. Getting Started

Installation

Anchor	Description
#nuget	Package installation
#packages-explained	Which packages for what

Creating Your Bot

Anchor	Description
#developer-portal	Creating application
#bot-token	Getting and securing token
#inviting-bot	OAuth2 URL, scopes, permissions

Project Setup

Anchor	Description
#generic-host	.NET Generic Host approach
#bare-bones	Manual setup approach
#configuration	appsettings.json

Running Your Bot

Anchor	Description
#starting-client	Starting GatewayClient
#verifying-connection	Ready event
#logging	Console output

Your First Response

Anchor	Description
#responding-to-messages	MessageCreate event
#responding-to-interactions	Slash command response
#using-components	Adding buttons

4. .NET Integration

.NET Generic Host

Anchor	Description
#why-generic-host	Benefits
#adding-gateway	AddDiscordGateway/UseDiscordGateway
#adding-services	UseApplicationCommands, etc.

Configuration

Anchor	Description
#appsettings	JSON configuration
#environment-variables	Secrets management
#options-pattern	GatewayClientOptions

Logging

Anchor	Description
#microsoft-logging	ILogger integration
#log-levels	Configuring verbosity
#custom-logging	IRestLogger, IGatewayLogger

5. Discord Entities

Overview

Anchor	Description
#entity-hierarchy	Base classes and inheritance
#rest-vs-gateway	RestGuild vs Guild
#caching	How entities are cached

Working with Users

Anchor	Description
#user-types	User, CurrentUser, GuildUser
#getting-users	Fetching user data
#user-properties	Username, avatar, etc.

Working with Guilds

Anchor	Description
#guild-types	Guild, RestGuild
#guild-properties	Name, icon, members
#guild-operations	Modifying guild

Working with Channels

Anchor	Description
#channel-types	Text, Voice, Category, Thread
#channel-hierarchy	IGuildChannel, ITextChannel
#sending-messages	Using channels to send

Roles and Permissions

Anchor	Description
#role-properties	Color, position, permissions
#permission-flags	Permissions enum
#checking-permissions	HasPermission methods
#permission-overwrites	Channel-specific permissions

Emojis and Stickers

Anchor	Description
#emoji-types	Emoji, GuildEmoji, ApplicationEmoji
#using-emojis	In messages, reactions
#stickers	Sticker types and usage

6. Events

Overview

Anchor	Description
#event-model	How events work in NetCord
#subscribing	+= syntax, handlers
#async-handlers	ValueTask pattern

Intents

Anchor	Description
#what-are-intents	Gateway intents explained
#privileged-intents	GuildMembers, Presences, MessageContent
#configuring-intents	GatewayClientConfiguration

Gateway Events

Anchor	Description
#connection-events	Ready, Resumed, Disconnected
#guild-events	GuildCreate, GuildUpdate, etc.
#message-events	MessageCreate, MessageUpdate, etc.
#interaction-events	InteractionCreate
#voice-events	VoiceStateUpdate, VoiceServerUpdate

Webhook Events

Anchor	Description
#webhook-event-types	WebhookEventType enum
#handling-webhook-events	WebhookEventHandler
#aspnetcore-integration	UseWebhookEvents()

7. Components v2

Overview

Anchor	Description
#enabling-v2	MessageFlags.IsComponentsV2
#component-limits	40 components max
#when-to-use	v2 vs legacy

Migrating from Embeds

Anchor	Description
#embeds-vs-components	Differences
#migration-patterns	Converting embed layouts

Layout Components

Anchor	Description
#container	ComponentContainerProperties
#section	ComponentSectionProperties
#separator	ComponentSeparatorProperties
#action-row	ActionRowProperties (legacy bridge)

Content Components

Anchor	Description
#text-display	TextDisplayProperties
#media-gallery	MediaGalleryProperties
#file-display	FileDisplayProperties
#thumbnail	ComponentSectionThumbnailProperties

Interactive Components

Anchor	Description
#buttons	ButtonProperties, LinkButtonProperties, PremiumButtonProperties
#button-styles	ButtonStyle enum
#select-menus	String, User, Role, Mentionable, Channel
#menu-options	MenuSelectOptionProperties

Modal Components

Anchor	Description
#label	LabelProperties
#text-input	TextInputProperties
#file-upload	FileUploadProperties
#modal-structure	ModalProperties

8. Commands

Overview

Anchor	Description
#command-types	Application vs Text commands
#when-to-use	Use cases for each
#services-framework	Link to Services Framework

Slash Commands

Anchor	Description
#creating-command	SlashCommandAttribute
#parameters	Parameter types
#options	Required, choices, autocomplete
#responding	InteractionCallback

User Commands

Anchor	Description
#creating-command	UserCommandAttribute
#target-user	Accessing target
#context-menu	How it appears in Discord

Message Commands

Anchor	Description
#creating-command	MessageCommandAttribute
#target-message	Accessing target
#context-menu	How it appears in Discord

Text Commands

Anchor	Description
#creating-command	CommandAttribute
#prefixes	Command prefixes
#parameters	Parameter parsing
#aliases	CommandAttribute aliases

9. Component Interactions

Message Components

Anchor	Description
#handling-buttons	ButtonInteraction
#handling-menus	StringMenuInteraction, etc.
#custom-id-pattern	Parsing CustomId
#parameters	ComponentInteractionParameter

Modals

Anchor	Description
#showing-modal	InteractionCallback.Modal()
#handling-submission	ModalInteraction
#accessing-values	TextInput.Value

10. Services Framework

Overview

Anchor	Description
#architecture	Service pattern explained
#shared-features	What's shared across services
#modules	Module base classes

Dependency Injection

Anchor	Description
#constructor-injection	Injecting services
#service-lifetime	Scoped vs Singleton
#service-provider	IServiceProvider

Type Readers

Anchor	Description
#built-in-readers	User, Role, Channel, etc.
#custom-readers	Creating custom readers
#registering-readers	Configuration

Preconditions

Anchor	Description
#built-in-preconditions	RequireUserPermissions, etc.
#custom-preconditions	PreconditionAttribute
#parameter-preconditions	ParameterPreconditionAttribute

Custom Contexts

Anchor	Description
#context-interfaces	IContext hierarchy
#creating-custom-context	Extending contexts
#accessing-context	In module methods

11. Webhooks

Overview

Anchor	Description
#what-are-webhooks	Webhook concept
#webhook-types	Incoming, Application

Managing Webhooks

Anchor	Description
#creating-webhooks	CreateWebhookAsync
#getting-webhooks	GetWebhooksAsync
#deleting-webhooks	DeleteWebhookAsync

Sending Messages

Anchor	Description
#webhook-client	WebhookClient
#message-properties	WebhookMessageProperties
#customizing-sender	Username, avatar override

12. Voice

Overview

Anchor	Description
#voice-architecture	VoiceClient, UDP, Opus
#prerequisites	libsodium, opus

Connecting to Voice

Anchor	Description
#joining-channel	JoinVoiceChannelAsync
#voice-events	VoiceStateUpdate flow
#disconnecting	LeaveVoiceChannelAsync

Audio Playback

Anchor	Description
#opus-encoding	OpusEncodeStream
#sending-audio	VoiceOutStream
#pcm-format	PcmFormat enum

Audio Recording

Anchor	Description
#receiving-audio	IVoiceReceiveHandler
#opus-decoding	OpusDecodeStream
#speaker-detection	Speaking event

Stream Types

Anchor	Description
#opus-encode-stream	Encoding PCM to Opus
#opus-decode-stream	Decoding Opus to PCM
#rewriting-stream	Stream transformation
#speed-normalizing	SpeedNormalizingStream

13. Advanced Topics

Sharding

Anchor	Description
#why-sharding	When you need it (2500+ guilds)
#sharded-client	ShardedGatewayClient
#shard-configuration	Shard count, shard IDs
#hosting-integration	UseShardedDiscordGateway

Caching Strategies

Anchor	Description
#cache-interface	IGatewayClientCache
#concurrent-vs-immutable	ConcurrentGatewayClientCache, ImmutableGatewayClientCache
#custom-cache	Implementing custom cache

Rate Limiting

Anchor	Description
#rate-limit-manager	IRateLimitManager
#handling-rate-limits	RestRateLimitHandling
#gateway-rate-limits	IRateLimiterProvider

Connection Resilience

Anchor	Description
#reconnect-strategies	Built-in strategies
#custom-strategy	Implementing custom
#disconnect-handling	Disconnected event

14. Deployment

Docker

Anchor	Description
#dockerfile	Sample Dockerfile
#docker-compose	Multi-service setup
#secrets	Managing tokens

Cloud Hosting

Anchor	Description
#azure	Azure App Service
#aws	AWS options
#vps	Generic VPS setup

15. Troubleshooting

Common Issues

Anchor	Description
#connection-issues	Gateway connection problems
#permission-issues	Bot permission errors
#rate-limit-issues	Being rate limited
#intent-issues	Missing intents

FAQ

Anchor	Description
#general	General questions
#commands	Command-related questions
#components	Component-related questions
#performance	Performance questions

[Mewyk]

Updated the main post with the latest concept as well as sections mapped (in section pages are very rough and very likely to change as this is just the initial plan for such). PR draft to come soon with the categories and sub categories (minimal content, but structure there).