Add API deprecation guidelines

Author: FaithOmbongi

.github/prompts/author-api-docs.prompt.md

@@ -15,11 +15,14 @@ Before beginning the documentation process, first ask the author which documenta
 **Please select your documentation scenario:**
 1. Author fresh APIs / fresh API changes to beta
 2. Promote APIs from beta to v1.0
+3. Document deprecated APIs
 
-**Please respond with 1 or 2 to proceed.**
+**Please respond with 1, 2, or 3 to proceed.**
 
 Once the author responds, follow the appropriate workflow below.
 
+**Note:** Scenario 3 (deprecation) can be combined with Scenario 1 or 2. If the Summary of API changes includes both deprecation and other changes (new APIs, promotions, updates), the workflow will handle mixed scenarios by processing non-deprecation tasks first, then applying deprecation documentation.
+
 ---
 
 ## Common Setup and Processes
@@ -514,6 +517,243 @@ Remove "(preview)" from TOC entries as applicable:
 
 ---
 
+## Scenario 3: Document deprecated APIs
+
+### Prerequisites
+
+**See [Common Setup: temp-docstubs Folder](#common-setup-temp-docstubs-folder)** for instructions on setting up the temp-docstubs folder.
+
+For this scenario, the author should add these files to `temp-docstubs`:
+- Summary of API changes documenting what is being deprecated
+- Autogenerated changelog file (changelog_*.json) if applicable
+- Any supporting documentation about the deprecation (blog post URLs, alternative APIs, migration guidance)
+
+### Understanding API deprecation
+
+A feature that is no longer in active development is _deprecated_. Deprecations are announced via blog posts and corresponding documentation updates. The deprecation announcement includes:
+- A timeline (deprecation period) after which the feature is removed from the service or the service is retired
+- Alternative features or workarounds for existing apps
+- Migration guidance and timelines
+
+**Important:** Deprecation is not always a standalone process. An API can be deprecated in the same set of changes that add new APIs. For example:
+- Deprecating one property while adding a replacement property
+- Deprecating a method while adding a new method
+- Deprecating a resource while adding an alternative resource
+- Combining deprecation with other API additions or updates
+
+The Summary of API changes may contain a mix of deprecation and new API documentation tasks.
+
+**API artifacts that can be deprecated:**
+- Resources (Entity Types and Complex Types)
+- Methods (CRUD operations, actions, functions)
+- Properties
+- Relationships (Navigation Properties)
+- Parameters (path, function, or query parameters)
+- Enumerations
+
+### Inputs required
+
+**Summary of API changes (required):**
+- Detailed description of what is being deprecated, which files to change, alternatives/workarounds, milestone dates, and blog post links
+- May include both deprecation and non-deprecation changes (mixed scenarios)
+- **Location:** `temp-docstubs` folder
+
+**Autogenerated changelog (optional):**
+- JSON file if provided
+- **Location:** `temp-docstubs` folder
+
+### Key principles
+
+- **Customer clarity:** Clearly indicate what is deprecated and provide alternatives/workarounds
+- **Implicit deprecation:** Deprecating a resource implies all its properties, methods, and relationships are deprecated (no need to mark each individually)
+- **Type definitions:** Deprecating a resource does NOT deprecate child type definitions unless explicitly stated
+
+### Common deprecation patterns
+
+**Deprecation banner (applies to resources, methods, enumerations with own topics):**
+- Place immediately after namespace declaration (before beta disclaimer if beta)
+- Format as CAUTION alert
+- Include: what's deprecated, milestone date, alternative/workaround, blog post link
+- Use include files stored in `api-reference/includes/` for consistency across topics
+
+**Example:**
+```markdown
+> [!CAUTION]
+> The Outlook tasks API is deprecated and will stop returning data on August 20, 2022. Use the [To Do API](https://learn.microsoft.com/graph/api/resources/todo-overview?view=graph-rest-1.0) instead.
+```
+
+**Table updates (applies to properties, relationships, parameters, enum members):**
+- Add "(deprecated)" to the name in the first column
+- Update description with alternative/workaround
+- Move to end of table, grouped alphabetically with other deprecated items
+- Do NOT add "(deprecated)" to JSON representation sections (causes validation errors)
+
+**TOC updates:**
+- Add `toc.title` attribute in YAML front matter with "(deprecated)" OR
+- Include "(deprecated)" inside link text in Methods tables
+
+---
+
+### To deprecate a resource
+
+1. **Update resource topic:**
+   - Add "(deprecated)" to H1 title: `# user resource type (deprecated)`
+   - Add deprecation banner (see common pattern above)
+   - Add `toc.title` with "(deprecated)" to YAML front matter
+
+2. **Mark child methods:**
+   - Add "(deprecated)" to H1 title in each method topic
+   - Add deprecation banner to each method topic
+
+3. **Update references in other resources:**
+   - Add "(deprecated)" to properties/relationships/methods that reference the deprecated resource type
+
+4. **Do NOT mark child type definitions as deprecated** (only if explicitly stated in Summary)
+
+---
+
+### To deprecate a method
+
+1. **Update method topic:**
+   - Add "(deprecated)" to H1 title: `# Delete user (deprecated)`
+   - Add deprecation banner with alternative/workaround
+
+2. **Update parent resource Methods table:**
+   - Add "(deprecated)" inside link text: `[Delete (deprecated)](user-delete.md)`
+   - Move to end of table (grouped alphabetically with other deprecated methods)
+   - Include alternative in description column
+
+---
+
+### To deprecate a property
+
+1. **Update resource Properties table:**
+   - Add "(deprecated)" to property name, update description with alternative, move to end (see common pattern)
+
+2. **Update API method topics:**
+   - Add "(deprecated)" in Request body tables (POST, PATCH, PUT) if property is used
+   - Update Response examples: remove property if no longer returned, keep if still returned
+
+---
+
+### To deprecate a relationship
+
+1. **Update resource Relationships table:**
+   - Add "(deprecated)" to relationship name, update description, move to end (see common pattern)
+
+2. **Deprecate corresponding methods:**
+   - Methods including the navigation property as a segment are also deprecated
+   - Follow method deprecation workflow for each affected method
+
+---
+
+### To deprecate a parameter
+
+**Update parameter table in method topic:**
+- Add "(deprecated)" to parameter name, specify whether to ignore or use alternative, move to end (see common pattern)
+
+---
+
+### To deprecate an enumeration
+
+1. **Update enumeration definition:**
+   - **In enums.md or parent resource:** Add "(deprecated)" to section title: `### emailType values (deprecated)`
+   - **In own topic (rare):** Add "(deprecated)" to H1 title and add deprecation banner
+
+2. **Update properties using the enum:**
+   - Update type, description, possible values with alternative/workaround
+
+---
+
+### To deprecate enumeration members
+
+1. **Update member table:**
+   - Add "(deprecated)" to member name, specify alternative, move to end (see common pattern)
+
+2. **Update property descriptions:**
+   - Note which values are deprecated and provide guidance
+
+---
+
+### Supporting updates
+
+**Changelog:** Change type: "Deprecation". Include API set/entities, link to topics and blog post. See [Common Process: Updating the Changelog](#common-process-updating-the-changelog).
+
+**What's New:** Describe deprecation, link to deprecated API and alternative, link to blog post. See [Common Process: Updating What's New](#common-process-updating-whats-new).
+
+---
+
+### Mixed scenarios
+
+When combining deprecation with new APIs/promotions:
+1. Categorize changes (deprecation, new, promotion, updates)
+2. Process non-deprecation tasks first (ensures alternatives are documented)
+3. Process deprecation tasks, referencing newly created alternatives
+4. Update changelog with both deprecation and addition/change entries
+
+---
+
+### Version-specific notes
+
+- **Beta:** Banner after namespace, before beta disclaimer; keep beta disclaimer; use `?view=graph-rest-beta&preserve-view=true`
+- **v1.0:** Banner after namespace; no query strings in links
+- **Both:** Apply to both versions; may have different milestone dates/alternatives
+
+---
+
+### Quality checklist
+
+**Common to all deprecations:**
+- [ ] "(deprecated)" added to H1 titles or table entries as appropriate
+- [ ] Deprecation banners added (resources, methods, enums with own topics): CAUTION alert after namespace, includes milestone/alternative/blog link
+- [ ] Include files used for banner text (best practice)
+- [ ] TOC updated: `toc.title` in YAML or "(deprecated)" in link text
+- [ ] Alternatives/workarounds provided and linked
+- [ ] "(deprecated)" NOT added to JSON representation sections
+
+**Table entries (properties, relationships, parameters, enum members):**
+- [ ] "(deprecated)" added to name in first column
+- [ ] Description updated with alternative
+- [ ] Moved to end of table (grouped alphabetically with other deprecated items)
+
+**Resources:**
+- [ ] All child methods marked deprecated with banners
+- [ ] References in other resources marked "(deprecated)"
+- [ ] Child type definitions NOT marked deprecated (unless explicitly stated)
+
+**Relationships:**
+- [ ] Corresponding methods with navigation property as segment also deprecated
+
+**Properties:**
+- [ ] "(deprecated)" added in Request body tables (POST/PATCH/PUT) if applicable
+- [ ] Response examples updated (removed if no longer returned, kept if still returned)
+- [ ] Description accuracy reviewed (e.g., "required" removed)
+
+**Enumerations:**
+- [ ] Section title or H1 title updated
+- [ ] Properties using enum updated with alternatives
+
+**Supporting updates:**
+- [ ] Changelog: Change type "Deprecation", links to topics/blog
+- [ ] What's New: describes deprecation, links to API/alternative/blog
+
+**Mixed scenarios:**
+- [ ] Non-deprecation tasks processed first
+- [ ] Deprecation references newly created alternatives
+- [ ] Changelog includes both deprecation and addition entries
+
+**Version-specific:**
+- [ ] Beta: Banner before beta disclaimer; beta disclaimer retained; links include `?view=graph-rest-beta&preserve-view=true`
+- [ ] V1.0: No query strings in links
+- [ ] Both versions: Applied to both with version-specific formatting
+
+**Final:**
+- [ ] All Summary items addressed
+- [ ] No markdown lint errors
+- [ ] Summary provided to author
+
+---
+
 ## Categories of changes (Scenario 1 only)
 
 Based on the summary of API changes, the work will fall into two categories: