# Doc Writer > Guidelines for producing accurate and maintainable documentation for Moq.AutoMocker. Use when writing or updating API docs, source generator docs, tutorials, README content, or any documentation in the docs/ folder. Use when this capability is needed. - Skill: `tomevault-io/doc-writer-7` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/doc-writer-7` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/doc-writer-7/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/doc-writer-7 --- # Documentation Writer Skill This skill provides guidelines for AI coding agents to help maintainers produce accurate and easy-to-maintain documentation for the Moq.AutoMocker project. The `docs/` folder contains the official documentation, and this skill helps ensure consistent, high-quality documentation. ## Documentation Overview ### Repository Structure **Location**: `docs/` **Audience**: .NET developers using Moq.AutoMocker for unit testing **Format**: Markdown files **API Reference**: Auto-generated from XML doc comments (do not edit manually) ### Documentation Categories ``` docs/ ├── Moq.AutoMock.md # Assembly overview (auto-generated) ├── PackageValidation.md # Package validation guide ├── SourceGenerators.md # Source generators overview ├── Moq.AutoMock/ # API reference (auto-generated) │ ├── AutoMocker.md │ ├── AutoMocker/ # AutoMocker member docs │ ├── MockExtensions.md │ ├── MockExtensions/ │ ├── ObjectGraphContext.md │ └── ObjectGraphContext/ ├── Moq.AutoMock.Resolvers/ # Resolver API reference (auto-generated) │ ├── IMockResolver.md │ ├── MockResolver.md │ ├── LazyResolver.md │ ├── EnumerableResolver.md │ └── ... └── SourceGenerators/ # Hand-written generator docs ├── UnitTestGenerator.md ├── OptionsExtensionGenerator.md ├── FakeLoggingExtensionGenerator.md ├── ApplicationInsightsExtensionGenerator.md └── KeyedServicesExtensionGenerator.md ``` ### What NOT to Edit Files in `docs/Moq.AutoMock/` and `docs/Moq.AutoMock.Resolvers/` are **auto-generated** from XML doc comments by `xmldocmd`. They contain the marker: ``` ``` Do not manually edit these files. Instead, update the XML doc comments in the source `.cs` files and regenerate. ## Markdown Conventions ### Frontmatter Documentation files in this project do **not** use frontmatter. Start directly with an H1 heading. ### Headings - Use H1 (`#`) for the page title only (one per file) - Use H2 (`##`) for major sections - Use H3 (`###`) for subsections - Do not skip heading levels ### Code Blocks Always include a language identifier: ````markdown ```csharp var mocker = new AutoMocker(); var service = mocker.CreateInstance(); ``` ```` For XML/MSBuild configuration: ````markdown ```xml false ``` ```` For JSON configuration: ````markdown ```json { "ConnectionStrings": { "mydb": "Host=localhost;Database=mydb" } } ``` ```` ### Tables Use standard Markdown tables with alignment: ```markdown | Column 1 | Column 2 | Column 3 | |----------|----------|----------| | Value | Value | Value | ``` ### Links Use relative links for internal documentation: ```markdown [AutoMocker API Reference](Moq.AutoMock/AutoMocker.md) [Source Generators](SourceGenerators.md) [Learn more →](SourceGenerators/UnitTestGenerator.md) ``` ## Source Generator Documentation ### File Location Place source generator docs in `docs/SourceGenerators/`: | Generator | File | |-----------|------| | Unit Test | `UnitTestGenerator.md` | | Options | `OptionsExtensionGenerator.md` | | Fake Logging | `FakeLoggingExtensionGenerator.md` | | Application Insights | `ApplicationInsightsExtensionGenerator.md` | | Keyed Services | `KeyedServicesExtensionGenerator.md` | ### Required Sections All source generator documentation must include these sections in order: 1. **Title and Introduction** — H1 title, when it activates, what it generates, primary value 2. **Features** — Bullet list of key capabilities 3. **Usage** — Basic usage with simple example, then advanced scenarios 4. **Generated Extension Methods** — Document the actual API generated with method signatures 5. **How It Works** — Internal mechanism explanation and integration with AutoMocker 6. **Advanced Usage** — Complex scenarios, type variations, working with dependencies 7. **Disabling the Generator** — MSBuild property configuration with `.csproj` example 8. **Troubleshooting** — Common issues with solutions 9. **Best Practices** — Practical, actionable guidance with code examples ### Introduction Template ```markdown # [Name] Extension Generator When your test project references `[Package.Name]`, this generator creates `[MethodName]()` extension method(s) for `AutoMocker` that [primary benefit]. ``` ### Features Template ```markdown ## Features - Automatically generates when `[Package.Name]` is referenced - [Key capability 1] - [Key capability 2] - [Integration benefit] ``` ### Disabling Generator Template All extension generators follow this MSBuild property pattern: ```xml false ``` Known properties: - `EnableMoqAutoMockerOptionsGenerator` - `EnableMoqAutoMockerFakeLoggingGenerator` - `EnableMoqAutoMockerApplicationInsightsGenerator` - `EnableMoqAutoMockerKeyedServicesGenerator` ### Troubleshooting Template ```markdown ## Troubleshooting ### Extension Method Not Available 1. Verify `[Required.Package]` is referenced in your test project 2. Check that the generator is not disabled in your `.csproj` 3. Rebuild the project to trigger generator execution ``` ### Updating the Overview After creating or updating generator documentation, update `docs/SourceGenerators.md`: 1. Update generator count in introduction if needed 2. Add/update numbered section with: - Link to detailed docs - One-sentence description - Key Features (3-4 bullets) - Quick Example (5-10 lines) - "Learn more →" link ## Code Example Standards ### Use MSTest by Default ```csharp [TestClass] public class MyServiceTests { [TestMethod] public void Test_DescriptiveScenario() { // Arrange AutoMocker mocker = new(); // Act var service = mocker.CreateInstance(); // Assert Assert.AreEqual(expected, actual); } } ``` ### Code Style Requirements - Use modern C# syntax (target-typed new, `var`) - Keep examples under 30 lines - Use realistic domain names (`EmailSender`, `NotificationService`, etc.) - Include `using` statements when relevant - Add comments only for non-obvious behavior - Use `// Arrange`, `// Act`, `// Assert` comments in test examples - Show both basic and advanced usage patterns ### Framework-Specific Examples When showing framework-specific content, use tables or separate code blocks: | Framework | Detection | Attributes Used | |-----------|-----------|-----------------| | **MSTest** | References `Microsoft.VisualStudio.TestTools.UnitTesting` | `[TestMethod]` | | **xUnit** | References `xunit.core` | `[Fact]` | | **NUnit** | References `nunit.framework` | `[Test]` | | **TUnit** | References `TUnit.Core` | `[Test]` (async) | ## Writing Style Guidelines ### Voice and Tone - Use **second person** ("you") when addressing the reader - Use **active voice** ("Create a mock" not "A mock is created") - Use **imperative mood** for instructions ("Add the attribute" not "You should add the attribute") - Be concise but complete - Be professional but approachable ### Terminology Use consistent terminology throughout: | Preferred | Avoid | |-----------|-------| | AutoMocker | auto mocker, Auto Mocker | | mock | fake, stub (unless technically accurate) | | source generator | code generator, analyzer | | extension method | helper method (for generated methods) | | `CreateInstance()` | create instance, build (when referring to the method) | | `GetMock()` | get mock (when referring to the method) | ### Formatting Conventions - Use **bold** for UI elements and important terms on first use - Use `backticks` for code references inline: types, methods, properties, parameters - Use "→" for "learn more" navigation links - Use ✅ and ❌ for correct/incorrect examples - Spell out numbers under 10, use digits for 10+ ## Project-Specific Context - **Package**: All source generators ship in the `Moq.AutoMock` NuGet package (not separate packages) - **Namespace**: Generated code is in the `Moq.AutoMock` namespace - **Target**: Extension methods extend the `AutoMocker` class - **Frameworks**: Supports MSTest, xUnit, NUnit, and TUnit - **Default State**: All generators are enabled by default - **Activation**: Most generators activate when specific NuGet packages are referenced - **Target Frameworks**: `netstandard2.0` and `netstandard2.1` ## Updating the README The project `README.md` at the repository root contains: - Badge links (CI, NuGet) - Quick-start usage examples - Links to the `docs/` folder When making significant documentation changes, ensure the README links and descriptions remain accurate. Keep README examples minimal — point readers to `docs/` for details. ## Common Patterns ### Diagnostic Error Documentation ```markdown ### AMG0001: Test class must be partial **Error:** When using `[ConstructorTests]`, your test class must be declared as `partial`. ```csharp // ❌ Error [ConstructorTests(TargetType = typeof(MyClass))] public class MyClassTests { } // ✅ Correct [ConstructorTests(TargetType = typeof(MyClass))] public partial class MyClassTests { } ``` ``` ### Feature with Before/After Examples Show the problem, then the solution: ```markdown **Without** the generator, you'd write this manually: ```csharp // 20+ lines of boilerplate... ``` **With** the generator, just add one attribute: ```csharp [ConstructorTests(TargetType = typeof(MyService))] public partial class MyServiceTests { } ``` ``` ### Cross-Referencing End pages with a "See also" section linking to: - Related generator documentation - AutoMocker API reference - NuGet package page - GitHub repository ```markdown ## See Also - [AutoMocker API Reference](../Moq.AutoMock/AutoMocker.md) - [Source Generators Overview](../SourceGenerators.md) - [Moq.AutoMock on NuGet](https://www.nuget.org/packages/Moq.AutoMock) ``` ## Testing Documentation Before submitting documentation: 1. **Verify links**: Ensure all internal links resolve to existing files 2. **Validate code**: Confirm all code examples compile and are consistent with current API 3. **Check structure**: Verify required sections are present and in order 4. **Review formatting**: Ensure Markdown renders correctly 5. **Analyze source**: Cross-reference generator docs against the actual source code in `Moq.AutoMocker.Generators/` and test examples in `GeneratorTests/` --- > Source: [moq/Moq.AutoMocker](https://github.com/moq/Moq.AutoMocker) — distributed by [TomeVault](https://tomevault.io).