Document examples

Reviewing generated documentation is much easier with something to compare against. Each page below is a complete, correct example of one document type, built from the templates the doc gen tooling actually uses.

They are reference material, not real documentation — the libraries and applications in them are fictional. Use them to answer "is this page shaped right?" while working through Reviewing documentation.

Every example shows the full markdown source, including YAML frontmatter, so you can compare fences, tables, and section order exactly as they appear in a generated file. Each one also links to a rendered copy of the same document, so you can check how it actually looks on the portal.

About the rendered copies

The rendered copies are laid out as a small, real documentation set, so links between them work — an operation page really does reach its business rules. Links pointing at documents outside the example set are shown as plain text rather than dead links.

Which examples apply to you

The documentation type in a repository's docgen-manifest.md decides which document set doc gen produces. Start with the group matching that type, then check the cross-cutting group, which can appear in any repository.

Framework / Component

Library-centric repositories. Documentation lives under docs/libraries/<slug>/, one set per library.

• overview.md — purpose, responsibilities, and key components for a single library.
• architecture.md — component structure, boundaries, and the required architecture diagram.
• api/<Type>.md — public type reference: members, signatures, and inherited behavior.
• business-rules.md — one section per rule, with per-rule Field/Value tables and BR IDs.
• operations-processes.md — the operation catalog and cross-operation hub, linking out to per-operation pages.
• operations/<slug>.md — the step-by-step detail page for a single operation.
• dependencies.md — internal and external dependencies with valid Reference Type values.
• configuration.md — settings the library reads, their defaults, and where they are consumed.

.NET (NCore) libraries use the same set, with these differences:

• service-registration.md — the registration extensions a library exposes, the services each registers and their lifetimes, and what a host must still register.
• configuration.md — IConfiguration, options binding, and environment variables instead of an <appSettings> catalog.
• packages.md — the repository-root package list for an SDK-packed library: pack method, target frameworks, bundled assemblies, and no .nuspec.

Web front end

Web applications add application-level and screen-level documentation on top of the library set, under docs/application/ and docs/screens/.

Three variants sit under this type, and their screen documents differ: a BOF WebForms screen describes .aspx controls, a .NET Framework 4 MVC / Razor screen describes controller actions and views, and an ASP.NET Core Razor Pages screen describes page handlers and routes. Check what a screen is built on before choosing an example.

BOF WebForms

• screens/<slug>.md — a single screen: purpose, controls, navigation, and its flow diagram.
• application/overview.md — what the application does and how its pieces fit together.
• application/business-rules.md — application-wide rules that screen documents anchor back to.
• application/dependencies.md — libraries and third-party components the application consumes, with reference types.
• application/tech-debt.md — genuine debt findings, including the expected NTLM authentication one.

.NET Framework 4 MVC / Razor

• screens/<slug>.md — a single screen: controller actions, views, Kendo UI widgets, and navigation.
• application/hosted-endpoints.md — the JSON, grid, and partial actions the application hosts for its own screens (the example shows the Core Razor Pages form; the .NET Framework 4 page has the same purpose and shape).

ASP.NET Core Razor Pages

• screens/<slug>.md — a single Razor Pages screen: route table, effective access, handler-based operations, dialogs and partials, hosted AJAX actions, and its flow diagram.
• application/architecture.md — host start-up, middleware order, route table, page-model hierarchy, layouts, and the Microsoft DI composition root.
• application/hosted-endpoints.md — named page handlers that return JSON, partials, or files, each linked back to the screens that call it.

Console app

Console and batch applications document the job itself — how it is invoked, what it processes, and how to recover it — under docs/applications/<slug>/.

Two families sit under this type, and they produce different documents. Which one you get depends on the framework the application is built on, so check the first page of the set before picking an example: a BOF batch application has a batch-lifecycle.md, a .NET Framework console application has a run-lifecycle.md and an arguments.md.

BOF batch applications

VB applications built on the BOF batch framework, with a Sub Main entry point, a batch class deriving from clsBatchBase, numeric return codes, and the File0/File1/File2 output streams.

• overview.md — what the job does, when it runs, and what it touches.
• batch-lifecycle.md — invocation, scheduling, and the processing sequence end to end.
• business-rules.md — rules enforced during batch processing, whether by the job or a consumed library.
• dependencies.md — libraries and third-party components the job consumes, with reference types.
• operational-runbook.md — failure modes, restart behavior, and manual intervention steps.
• data-model.md — tables and objects the job reads and writes.

.NET Framework console applications

C# applications built on SAIF.Framework.Windows, with a Program.Run() entry point, named arguments resolved through an argument container, dependency registration, and exit codes inherited from the SaifConsoleException hierarchy.

• overview.md — purpose, invocation, scheduling, and capabilities.
• run-lifecycle.md — argument resolution, dependency registration, and the Initialize / Execute / Finish sequence.
• arguments.md — the full argument contract: syntax forms, validation, and what a resolution failure does.
• configuration.md — Environment API settings and the App.config surface.
• dependencies.md — framework packages, transitive dependencies, API clients, and database configurations.
• operational-runbook.md — console output, log files, exit codes, and recovery procedures.

Rest API

REST services document the endpoints they expose under docs/apis/<api-slug>/. There are no screen documents — a service with no user interface should never have any.

The examples below show the .NET Framework 4 Web API shape; the ASP.NET Core Web API pages follow them.

• index.md — the service fact table, section map, and controller catalog.
• overview.md — purpose, consumers, and capability summary.
• architecture.md — hosting, request pipeline, layering, and the DI composition root.
• endpoints.md — the endpoint catalog, linking out to per-controller pages.
• endpoints/<slug>.md — one controller: every route, its request and response shapes, and the rules it enforces.
• authentication-authorization.md — identity, authorization enforcement, and role requirements.
• business-rules.md — rules enforced during request processing.
• operational-runbook.md — deployment, health checks, status codes, and error recovery.

The examples above show the .NET Framework 4 Web API shape. ASP.NET Core Web API documents use the same page names, plus a hosting-pipeline.md, with resolved route templates and .NET configuration:

ASP.NET Core Web API

• hosting-pipeline.md — the ordered middleware pipeline, with package-contributed behavior marked.
• endpoints.md — the endpoint catalog with resolved route templates and minimal-API endpoints.
• configuration.md — appsettings*.json, options binding, IEnvironmentClient, and environment variables.

API client packages

A package that wraps a REST API is documented separately, under docs/clients/<client-slug>/, whether it ships from its own repository or alongside the API it calls.

• index.md — package identity and the wrapped API.
• package.md — nuspec identity, version, dependencies, shipped content, and the publishing pipeline.
• reference.md — one section per public member of the client interface.
• endpoint-map.md — client method to API endpoint traceability.
• consumption.md — how a consumer constructs and calls the client.

The examples above show a .NET Framework client. ASP.NET Core clients use the same page names:

• package.md — describes the SDK project instead of a nuspec.
• consumption.md — the DI registration extension.
• endpoint-map.md — adds a ## Route drift section comparing client routes with the API's actual routes.

SOAP service

SOAP services document each hosted service under docs/services/<service-slug>/. Both WCF (.svc, [ServiceContract]) and ASMX (.asmx) are filed under this type, and the manifest's classification basis says which one a repository is.

WCF

• index.md — the service fact table, section map, and contract catalog.
• contracts/<slug>.md — one service contract: its operations, data contracts, and fault contracts.
• faults.md — fault contracts and how errors reach the caller.

ASMX

• activation-hosting.md — how an .asmx service is hosted and activated, which differs from WCF.

SOAP client proxies

A package that wraps a consumed SOAP service is documented under docs/clients/<client-slug>/.

• operation-map.md — proxy operations traced to the service operations they call.
• consumption.md — how a consumer constructs and calls the proxy.

Cross-cutting

These appear in any repository type whenever the analysis detects them.

• security-authorization.md — real AD resources with a purpose and a sourced enforcement point.
• sql/index.md — the SQL catalog: every statement the code issues, grouped by operation type.
• sql/SQL-<name>.md — one SQL statement: classification, parameters, and the real SQL.
• procedures/index.md — the catalog of stored procedures and packages the code invokes.
• procedures/<name>.md — one stored procedure or package, retrieved through the Legends CLI.
• docgen-manifest.md — the root manifest whose documentation type files the repo in this portal.

Examples show shape, not correctness

A page matching its example is well-formed. It is not necessarily accurate — only someone who knows the system can confirm the content is true. Keep both halves of the review in view.