Azure / Azure/azure-sdk-for-python

Propose documentation layout specification

Offen
#45,781 1 Kommentar 0 Reaktionen 1 zugewiesene Person Beansprucht von @laiapat Auf GitHub ansehen
Vorherrschende Sprache
Python
Sterne
5.6k
Forks
3.4k
Ø Merge
2 T. 2 Std.
Gemergte PRs (30 T.)
213

Beschreibung

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:

```text
azure-sdk-for-*/
|
--> doc/
|
--> contribution/
| |
| -->
| |
| --> {service}/
| |
| -->
--> usage/
|
-->
```

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.

To help guide categorization, we can refer to this summary of documentation practices across language repos: https://gist.github.com/christothes/d05ac1c1bec2510e0fd5f90cc8eac1ae

Beitragsleitfaden

Beitragsleitfaden öffnen

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.