Azure / Azure/azure-rest-api-specs

Clean Up Legacy AutoRest Documentation Under documentation

Open
#44,535 0 comments 0 reactions 0 assignees View on GitHub
Docs Epic
Dominant language
TypeSpec
Stars
3.1k
Forks
5.9k
Avg merge
3d 2h
Merged PRs (30d)
424

Description

### Background
The Azure REST API Specs repository has transitioned toward TypeSpec as the primary authoring experience. However, the documentation folder still contains guidance that references legacy AutoRest-based workflows, tooling, configurations, and processes.

### Actions

- Review documents under documentation for legacy AutoRest references.
- Remove obsolete content that no longer provides value.
- Add deprecation notices where historical guidance should remain available for reference.
- Update links and references to point to TypeSpec-based workflows and tooling.
- Ensure service teams can easily identify the recommended authoring and validation experience.

Out of Scope
- Functional changes to TypeSpec tooling.
- SDK generation pipeline changes.
- Changes outside the documentation directory unless required to fix broken references.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the documentation directory and searching for legacy AutoRest references, workflows, tooling, configurations, and processes. Identify which guidance is obsolete, which needs a deprecation notice, and which links should point to TypeSpec workflows. Done means the documentation clearly identifies the recommended authoring and validation experience without changing TypeSpec tooling or SDK pipelines.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.