From b27081dbec9fbb262eca5656944f928487126551 Mon Sep 17 00:00:00 2001 From: John Haugabook Date: Sun, 29 Mar 2026 17:08:51 -0400 Subject: [PATCH] new instruction use-cliche-data-in-docs.instructions (#1203) * new instruction use-cliche-data-in-docs.instructions * Update instructions/use-cliche-data-in-docs.instructions.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/README.instructions.md | 1 + .../use-cliche-data-in-docs.instructions.md | 115 ++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 instructions/use-cliche-data-in-docs.instructions.md diff --git a/docs/README.instructions.md b/docs/README.instructions.md index 082e37d0..8e2a1e3f 100644 --- a/docs/README.instructions.md +++ b/docs/README.instructions.md @@ -188,6 +188,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on | [Update Code from Shorthand](../instructions/update-code-from-shorthand.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fupdate-code-from-shorthand.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fupdate-code-from-shorthand.instructions.md) | Shorthand code will be in the file provided from the prompt or raw data in the prompt, and will be used to update the code file when the prompt has the text `UPDATE CODE FROM SHORTHAND`. | | [Update Documentation on Code Change](../instructions/update-docs-on-code-change.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fupdate-docs-on-code-change.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fupdate-docs-on-code-change.instructions.md) | Automatically update README.md and documentation files when application code changes require documentation updates | | [Upgrading from .NET MAUI 9 to .NET MAUI 10](../instructions/dotnet-maui-9-to-dotnet-maui-10-upgrade.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-maui-9-to-dotnet-maui-10-upgrade.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-maui-9-to-dotnet-maui-10-upgrade.instructions.md) | Instructions for upgrading .NET MAUI applications from version 9 to version 10, including breaking changes, deprecated APIs, and migration strategies for ListView to CollectionView. | +| [Use Cliche Data in Documentation](../instructions/use-cliche-data-in-docs.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fuse-cliche-data-in-docs.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fuse-cliche-data-in-docs.instructions.md) | Ensure documentation and examples use only generic, cliche placeholder data — never real or sensitive data sourced from local scripts, configuration, task files, or prompt context. | | [Use Code Components in Power Pages](../instructions/pcf-power-pages.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-power-pages.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-power-pages.instructions.md) | Using code components in Power Pages sites | | [Visual Studio Extension Development with Community.VisualStudio.Toolkit](../instructions/vsixtoolkit.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fvsixtoolkit.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fvsixtoolkit.instructions.md) | Guidelines for Visual Studio extension (VSIX) development using Community.VisualStudio.Toolkit | | [WinUI 3 / Windows App SDK](../instructions/winui3.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fwinui3.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fwinui3.instructions.md) | WinUI 3 and Windows App SDK coding guidelines. Prevents common UWP API misuse, enforces correct XAML namespaces, threading, windowing, and MVVM patterns for desktop Windows apps. | diff --git a/instructions/use-cliche-data-in-docs.instructions.md b/instructions/use-cliche-data-in-docs.instructions.md new file mode 100644 index 00000000..56cf976f --- /dev/null +++ b/instructions/use-cliche-data-in-docs.instructions.md @@ -0,0 +1,115 @@ +--- +description: 'Ensure documentation and examples use only generic, cliche placeholder data — never real or sensitive data sourced from local scripts, configuration, task files, or prompt context.' +applyTo: '**/*.{md,js,mjs,cjs,ts,tsx,jsx,py,json}' +--- + +# Use Cliche Data in Documentation + +When updating or writing documentation for a tool, **never include real data** that was provided in prompts, local configuration, scripts, task files, or any other implementation-specific source. Documentation must use only generic, commonly recognized placeholder data that cannot expose sensitive information. + +## Why This Matters + +A tool's source code and local configuration often contain real names, real email addresses, real organization details, and real domain names. These values are necessary for the tool to function, but they have **no place in public-facing documentation**. Leaking real data into docs can expose: + +- Internal business names and contacts +- Email addresses and domain names +- Client or customer identifiers +- Account names and credentials +- Organization-specific terminology that reveals private operations + +## Core Rule + +> **If data came from a prompt, a local file, a script, a config, or a task — it does NOT go into documentation.** +> +> Documentation examples use only well-known, fictional, or obviously placeholder data. + +## What Counts as Real Data + +Any value that originates from: + +- **Local configuration files** (e.g., `config.json`, `.env`, account modules) +- **Scripts and task files** (e.g., batch scripts, shell scripts, task runners) +- **Prompt context** (e.g., data the user supplies when asking an agent to build or update the tool) +- **Map or filter files** (e.g., JSON mappings, data extraction rules) +- **Git-ignored files** (e.g., files excluded from version control that contain environment-specific values) + +## Approved Placeholder Data for Documentation + +Use these generic, cliche substitutes in all documentation and examples: + +| Category | Approved Placeholder Examples | +| --- | --- | +| **People** | Jane Doe, John Smith, Alice, Bob | +| **Email addresses** | `jane.doe@example.com`, `admin@example.org` | +| **Organizations** | Acme Corp, Contoso, Northwind Traders | +| **Domains** | `example.com`, `example.org`, `example.net` | +| **Addresses** | 123 Main Street, Suite 100, Springfield | +| **Phone numbers** | `(555) 123-4567` | +| **Accounts / usernames** | `demo-user`, `test-account` | +| **File paths** | `accounts/acme.mjs`, `config/reports.json` | +| **Project names** | My Project, Sample App, Demo Tool | + +## How to Apply This Rule + +### When Adding a Feature + +If you add a feature using real account data (e.g., a script named after a real client), document the feature using a fictional account name instead. + +**Real implementation file:** an account module configured for a specific business + +**Documentation example:** + +```javascript +// accounts/acme.mjs — Example account configuration +export default { + name: 'Acme Corp', + email: 'reports@example.com', + folder: 'INBOX', +}; +``` + +### When Updating Configuration Docs + +If a config file references real domains, real paths, or real credentials, replace every real value with a placeholder before including it in documentation. + +**Documentation example:** + +```json +{ + "host": "imap.example.com", + "user": "admin@example.com", + "folder": "INBOX/Reports", + "outputDir": "./downloads" +} +``` + +### When Writing Script Examples + +If a script automates a task for a specific organization, the documentation example must use a generic organization name and generic parameters. + +**Documentation example:** + +```batch +@echo off +REM Example: Run the extraction task for Acme Corp +node extractEmail.mjs --account acme --task download +``` + +## The Boundary Between Code and Docs + +| Context | Real Data Allowed? | +| --- | --- | +| Local scripts and config files used at runtime | Yes | +| Git-ignored files with environment-specific values | Yes | +| Prompt data provided to build or configure the tool | Yes (in code only) | +| README.md, docs/ folder, and example templates | **No — use placeholders only** | +| CHANGELOG.md entries | **No — describe changes generically** | +| Code comments in committed source files | **No — keep generic** | + +## One Exception + +A word from real data may appear in documentation **only** if it is a common English word used in its ordinary sense and **not** in the context of an example. For instance, the word "development" is acceptable in a sentence like "This tool is under active development" even if it also appears in a real organization name. + +## Summary + +Documentation is public. Implementation data is private. Keep them separate. Every example in every doc file should pass a simple test: *could a stranger read this and learn nothing about the real users, clients, or organizations behind this tool?* If the answer is no, replace the data with cliche placeholders.