Skip to content

Propose documentation layout specification #45781

@mccoyp

Description

@mccoyp

We should have a relatively common layout for repository documentation, such that an agent can determine where to look for a category of guidance regardless of programming language. For example:

azure-sdk-for-*/
|
--> doc/
    |
    --> contribution/
    |   |
    |   --> <SDK-wide guidance; e.g. testing>
    |   |
    |   --> {service}/
    |       |
    |       --> <service-specific developer guidance>
    --> usage/
        |
        --> <SDK-wide guidance; e.g. logging>

The divisions should be clearly separated by intended audience and scope.

Note: we should still follow standard conventions where applicable. For example, open-source repositories should have a CONTRIBUTING.md describing how to contribute as a developer -- we should keep CONTRIBUTING.md files and maybe use them as an index to point to where our specific documentation lives. This also allows us to prompt engineer in a way by assigning weight to particular sources/categories.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions