Azure / Azure/azure-sdk-tools

Investigate and update TypeSpec/SDK generation docs to include AzSDK Tools Agent guidance

Open
#14,597 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

AzSDK Tools Agent
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 2h
Merged PRs (30d)
130

Description

Description

Investigate the azure-rest-api-specs repo and Azure SDK language repos (e.g., azure-sdk-for-python, azure-sdk-for-js, azure-sdk-for-java, azure-sdk-for-net, azure-sdk-for-go) to find documentation covering the TypeSpec authoring and SDK generation process. Currently, these docs reference the old manual approach (custom scripts, tsp client commands, etc.) without mentioning the Azure SDK Tools Agent as the recommended path.

The goal is to ensure service teams see the agent-first approach prominently in these docs, with the manual process available as a fallback.

Phase 1 — Investigation & Report

  • Search the repos above for documentation that references the manual TypeSpec/SDK generation workflow (e.g., tsp client, tsp init, custom generation scripts, manual PR creation).
  • For each doc found, note:
    • File path and repo
    • What manual process it describes
    • Whether it already mentions the Azure SDK Tools Agent
  • Produce a report summarizing all findings.

Phase 2 — Documentation Updates

  • For docs that only reference the old manual process, create draft PRs to update them:
    • Add guidance on how to accomplish the same tasks using the Azure SDK Tools Agent.
    • Position the agent-first approach prominently (before the manual steps).
    • Include a link to the agent docs on first mention: https://aka.ms/azsdk/agent
  • Open all PRs as drafts for review.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Search azure-rest-api-specs and the azure-sdk-for-python, azure-sdk-for-js, azure-sdk-for-java, azure-sdk-for-net, and azure-sdk-for-go repositories for “tsp client,” “tsp init,” custom generation scripts, and manual PR guidance. Record each document’s path, manual workflow, and agent coverage, then prepare draft PRs that put the Azure SDK Tools Agent guidance first, link https://aka.ms/azsdk/agent, and retain manual steps as fallback.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure, csharp, go, java, javascript, python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.