Azure / Azure/azure-dev

Decide extension documentation publishing strategy

Open
#6,239 0 comments 0 reactions 1 assignee Claimed by @kristenwomack View on GitHub
area/docs area/extensions engineering item
Dominant language
Go
Stars
569
Forks
364
Avg merge
2d 19h
Merged PRs (30d)
136

Description

## Description

Establish a clear strategy for how extension documentation will be published, ensuring discoverability and consistency while supporting both first-party and community extensions.

## Key Questions to Answer

### First-Party Extensions (in our repo)

- [ ] Should these live on main docs site (learn.microsoft.com)?
- [ ] How do we organize extension docs alongside core CLI docs?
- [ ] What's the publication workflow (automated vs. manual)?
- [ ] How do we version extension docs separately from core?

### Community/Third-Party Extensions

- [ ] Do we provide a template or example for extension docs?
- [ ] Where should third-party extension docs be hosted (their repos, central catalog)?
- [ ] How do we ensure quality and discoverability?
- [ ] Should we have a registry of extension documentation links?

### Documentation Template

- [ ] Create standard template for extension documentation
- [ ] Define required sections (installation, usage, configuration, etc.)
- [ ] Include examples and best practices
- [ ] Provide markdown template for easy adoption

## Acceptance Criteria

### Strategy Document

- [ ] Document decision on first-party extension docs publishing
- [ ] Define publication workflow and tooling
- [ ] Establish standards for extension documentation
- [ ] Create template and guidelines for extension authors

### Implementation

- [ ] Set up docs infrastructure if needed (automated publishing, etc.)
- [ ] Migrate existing extension docs to chosen approach
- [ ] Create template repository or documentation
- [ ] Test with at least one extension

### Communication

- [ ] Publish guidelines for extension authors
- [ ] Update extension developer documentation
- [ ] Communicate strategy to team and community

## Considerations

- Discoverability: How do users find extension docs?
- Maintenance: Who maintains first-party vs. third-party docs?
- Versioning: How to handle docs for multiple extension versions?
- Search: Should extension docs be searchable on main docs site?

## Benefits

- Clear expectations for extension documentation
- Better discoverability for users
- Consistent documentation quality
- Easier for community to contribute extensions

## Parent Issue

- #5767 (Extension enhancements EPIC)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.