Skip to main content

Documentation Framework (Backend Modules)

This framework defines how backend module documentation should be structured and written. It is optimized for .NET modules and beginner-friendly onboarding.

  • Each module appears as a sidebar category.
  • The first subpage is always Overview.
  • If the module has provider options (for example: Local, Azure AD, Auth0), list those providers as subpages instead of a generic integration guide.
  • If there are no providers, the second subpage is Integration Guide.
  • Do not create empty pages.

Overview page rules​

  • No code blocks in the Overview page.
  • Explain what the module does, who it is for, and where it fits.
  • List key capabilities and core concepts.
  • List packages and adapters.
  • Link to any related frontend UI modules and related backend modules.
  • Keep wording simple and consistent across modules.

Integration guide rules (5-step pattern)​

Each integration guide follows these five steps in order:

  1. Install the package.
  2. Configure Program.cs and required middleware.
  3. Configure appsettings.json.
  4. Configure endpoints.
  5. Test the endpoint.

If configuration values or tokens require external setup, include a <details> section under Step 3 titled "How to get configuration values".

Terminology and consistency​

  • Use attribute for RBAC condition inputs. Avoid the term claim unless it is a JWT claim or identity token field.
  • Keep package names and namespaces consistent with the published artifacts.
  • Avoid emojis and informal phrasing.

Non-goals section​

A non-goals section is optional. It clarifies what the module intentionally does not do, which prevents incorrect expectations. Use it only if the module has common misconceptions or expected features that it does not include.