Draft: Introduction for the Documentation category

Documentation
1

The Documentation category’s intro post contains a default now. Here’s a draft that several of us came up with. Improvements welcome. I’ll ask admins to put it up when discussion dies down.

This is the hub for discussion around all aspects of Python’s documentation.

This category is for anyone who wants to contribute, including readers giving feedback.
It’s also the place to discuss specific technical and editorial issues with the docs, particularly:

  • Organization
  • Style guides
  • Visual styles/themes
  • Build system

Scope

All technical writing related to the Python project is in scope, including:

To report problems which don’t need wide discussion, use the appropriate project’s issue tracker instead (e.g. bugs.python.org for Python’s docs).

Translations

For starting a new translation, feel free to hold initial discussions here (in English).

For other translation-related discussions, follow the links and instructions in the developer’s guide.

Source text: 
This is the hub for discussion around all aspects of Python's documentation. 

This category is for anyone who wants to contribute, including readers giving feedback.
It's also the place to discuss specific technical and editorial issues with the docs, particularly:

- Organization
- Style guides
- Visual styles/themes
- Build system

## Scope

All technical writing related to the Python project is in scope, including:

- [Python Documentation](https://docs.python.org/3/)
- [Python Developer's Guide](https://devguide.python.org/)
- [PEP](https://peps.python.org/) editing

To report *problems* which don't need wide discussion, use the appropriate project's issue tracker instead (e.g. [bugs.python.org](http://bugs.python.org) for Python's docs).

## Translations

For [starting a new translation](https://devguide.python.org/documenting/#starting-a-new-translation), feel free to hold initial discussions here (in English).

For other translation-related discussions, follow the [links and instructions in the developer's guide](https://devguide.python.org/documenting/#translating).

The text is also on a HackMD pad, feel free to edit there.

3 Likes
2

Could you post the raw markdown, to make it easier to suggest changes?

3

Based on the followup changes that were just made, I made a few additional copyedits in the HackMD to fix a couple grammar and phrasing issues, link to the PEPs like the other two, and reword “consumers” to “readers” which is much friendlier, more appropriate and widely understood. Reposting them here rendered:

This is the place to discuss Python’s documentation, including:

  • Organization
  • Style guides
  • Visual styles/themes
  • Build systems

The category is for anybody that feels a part of contributions to the docs, including readers giving feedback.

All technical writing related to the Python project is in scope, including:

To report problems which don’t need wide discussion, use the appropriate project’s issue tracker instead (e.g. bugs.python.org for Python’s docs).

To discuss a translation to a specific language, follow the links and instructions in the Devguide. For starting a new translation, feel free to hold initial discussions here (in English).

and as text:

This is the place to discuss Python's documentation, including:

- Organization
- Style guides
- Visual styles/themes
- Build systems

The category is for anybody that feels a part of contributions to the docs, including readers giving feedback.

All technical writing related to the Python project is in scope, including:

- [Python documentation](https://docs.python.org/3/)
- The [Devguide](https://devguide.python.org/)
- [PEP](https://peps.python.org/) editing

To report *problems* which don't need wide discussion, use the appropriate project's issue tracker instead (e.g. [bugs.python.org](http://bugs.python.org) for Python's docs).

To discuss a translation to a specific language, follow the [links and instructions in the Devguide](https://devguide.python.org/documenting/?highlight=translations#translating). For [starting a new translation](https://devguide.python.org/documenting/?highlight=translations#starting-a-new-translation), feel free to hold initial discussions here (in English).
1 Like
4

Thanks, CAM, I put your revision in the initial post (with an additional simplification).
And I added the raw source text there.

The text is also on a HackMD pad, feel free to edit it there.

1 Like
5

I’ve gone ahead and directly editted the HackMD. The markup is below, in case we lose it to HackMD’s limited-when-free revision history. :slight_smile:

This is the place to discuss Python's documentation and for anyone who wants to contribute to the documentation, including readers giving feedback. 

This is also the place for wide discussion about the following aspects of Python's documentation:

- Organization
- Style guides
- Visual styles/themes
- Build system

## Scope

All technical writing related to the Python project is in scope, including:

- [Python Documentation](https://docs.python.org/3/)
- [Python Developer's Guide](https://devguide.python.org/)
- [PEP](https://peps.python.org/) editing

To report *problems* which don't need wide discussion, use the appropriate project's issue tracker instead (e.g. [bugs.python.org](http://bugs.python.org) for Python's docs).

## Translations

For [starting a new translation](https://devguide.python.org/documenting/#starting-a-new-translation): feel free to hold initial discussions here (in English).

For other translation-related discussions, follow the [links and instructions in the developer's guide](https://devguide.python.org/documenting/#translating).
6

I made some additional copyediting revisions in the HackMD to the first few lines to reduce redundancy and repetition (e.g. “this is the place to discuss Python’s documentation”/“this is also the place for wide discussion about all aspects of Python’s documentation”) and improve the phrasing and choppiness.

Rendered

This is the hub for discussion around all aspects of Python’s documentation.

This category is for anyone who wants to contribute, including readers giving feedback.
It’s also the place to discuss specific technical and editorial issues with the docs, particularly:

  • Organization
  • Style guides
  • Visual styles/themes
  • Build system

Scope

All technical writing related to the Python project is in scope, including:

To report problems which don’t need wide discussion, use the appropriate project’s issue tracker instead (e.g. bugs.python.org for Python’s docs).

Translations

For starting a new translation, feel free to hold initial discussions here (in English).

For other translation-related discussions, follow the links and instructions in the developer’s guide.


Source 
This is the hub for discussion around all aspects of Python's documentation. 

This category is for anyone who wants to contribute, including readers giving feedback.
It's also the place to discuss specific technical and editorial issues with the docs, particularly:

- Organization
- Style guides
- Visual styles/themes
- Build system

## Scope

All technical writing related to the Python project is in scope, including:

- [Python Documentation](https://docs.python.org/3/)
- [Python Developer's Guide](https://devguide.python.org/)
- [PEP](https://peps.python.org/) editing

To report *problems* which don't need wide discussion, use the appropriate project's issue tracker instead (e.g. [bugs.python.org](http://bugs.python.org) for Python's docs).

## Translations

For [starting a new translation](https://devguide.python.org/documenting/#starting-a-new-translation), feel free to hold initial discussions here (in English).

For other translation-related discussions, follow the [links and instructions in the developer's guide](https://devguide.python.org/documenting/#translating).
1 Like
7

Looks good!
I plan to wrap this up on Wednesday.

2 Likes