docs/tickets

[Repo alignment] Write a common README for all docs projects and set it everywhere #36

New issue

Closed

opened 2026-05-05 10:21:06 +00:00 by pbokoc · 7 comments

pbokoc commented

2026-05-05 10:21:06 +00:00

Owner

Subset of #18.

We need to come up with a shorter README for docs repos. The new README should:

Have a short explanation of the repo's topic
Link to where the docs are published (the output URL)
Link to contributor docs
Contain info about who is responsible for said docs and a contact link (Matrix channel, mailing list, team page in docs, ...)
NOT include the part about repo structure etc. - that belongs in contributor docs so we can maintain it in one place

And in order to close this issue, all repositories in the docs organization (except "service" repos like tickets) should use it. Published repositories outside the docs org should be left to do whatever they want, though we should let them know they might want to follow our lead.

Subset of #18. We need to come up with a shorter README for docs repos. The new README should: - Have a short explanation of the repo's topic - Link to where the docs are published (the output URL) - Link to contributor docs - Contain info about who is responsible for said docs and a contact link (Matrix channel, mailing list, team page in docs, ...) - NOT include the part about repo structure etc. - that belongs in contributor docs so we can maintain it in one place And in order to close this issue, all repositories in the [docs](https://forge.fedoraproject.org/docs) organization (except "service" repos like tickets) should use it. Published repositories outside the docs org should be left to do whatever they want, though we should let them know they might want to follow our lead.

pbokoc added the

needs changes

label

2026-05-05 10:21:06 +00:00

pbokoc self-assigned this

2026-05-05 10:21:06 +00:00

pbokoc referenced this issue

2026-05-05 10:43:33 +00:00

Repository alignment #18

pbokoc added a new dependency

2026-05-05 13:57:35 +00:00

#18 Repository alignment

pbokoc added this to the (deleted) project

2026-05-05 15:07:33 +00:00

mwinters referenced this issue

2026-05-13 19:47:52 +00:00

Create a "code style guide" for docs #44

jonashub commented

2026-05-25 17:59:17 +00:00

Member

Here's my suggestion for the common README. Let me know what do you think. ;)

# Fedora [NAME] Documentation

[SHORT DESCRIPTION – 1-2 sentences about what the documentation covers]

## Published documentation

The published version of this documentation is available at:
[docs.fedoraproject.org/en-US/...](https://docs.fedoraproject.org)

## Contributing

We welcome contributions! Whether it's fixing a typo, reporting an outdated
page, or writing new content — every little bit helps.

See the [Fedora Docs Contributor Guide](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/)
for how to get started.

Please report **content issues** in this repository.
For general site/publishing issues, use the
[Fedora Docs Website repository](https://forge.fedoraproject.org/docs/docs-fp-o).

## Contact
- **Matrix:** [#docs:fedoraproject.org](https://matrix.to/#/#docs:fedoraproject.org)
- **Private comms:** Use our FAS emails for anything that shouldn't be public.
- **Discussion forums:** [discussion.fedoraproject.org](https://discussion.fedoraproject.org/tag/docs-team/337)

Here's my suggestion for the common README. Let me know what do you think. ;) ``` # Fedora [NAME] Documentation [SHORT DESCRIPTION – 1-2 sentences about what the documentation covers] ## Published documentation The published version of this documentation is available at: [docs.fedoraproject.org/en-US/...](https://docs.fedoraproject.org) ## Contributing We welcome contributions! Whether it's fixing a typo, reporting an outdated page, or writing new content — every little bit helps. See the [Fedora Docs Contributor Guide](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/) for how to get started. Please report **content issues** in this repository. For general site/publishing issues, use the [Fedora Docs Website repository](https://forge.fedoraproject.org/docs/docs-fp-o). ## Contact - **Matrix:** [#docs:fedoraproject.org](https://matrix.to/#/#docs:fedoraproject.org) - **Private comms:** Use our FAS emails for anything that shouldn't be public. - **Discussion forums:** [discussion.fedoraproject.org](https://discussion.fedoraproject.org/tag/docs-team/337) ```

theprogram commented

2026-05-25 19:09:55 +00:00

Member

I like it.

As it is for totally new people, I do not think they will know what 'including a local preview' means. So we could leave that out, and make sure the links are there from the Contributor Guide.

I like it. As it is for totally new people, I do not think they will know what 'including a local preview' means. So we could leave that out, and make sure the links are there from the Contributor Guide.

jonashub commented

2026-05-26 08:05:41 +00:00

Member

Good point. I'll remove it.

pbokoc added the

labels

2026-05-29 12:10:16 +00:00

pbokoc commented

2026-05-29 12:14:58 +00:00

Author

Owner

A couple more things @jonashub

Replace the Matrix room name with this link: https://matrix.to/#/#docs:fedoraproject.org
Add a link to the forums: https://discussion.fedoraproject.org/tag/docs-team/337

If you don't mind, please edit it into the post above so I can copypaste it later and not worry about it :)

A couple more things @jonashub * Replace the Matrix room name with this link: https://matrix.to/#/#docs:fedoraproject.org * Add a link to the forums: https://discussion.fedoraproject.org/tag/docs-team/337 If you don't mind, please edit it into the post above so I can copypaste it later and not worry about it :)

👍 1

pbokoc referenced this issue from discussion/self-moderation-guidelines-and-rules

2026-06-01 07:13:43 +00:00

Fix README #1

jonashub referenced this issue from a commit

2026-06-02 17:48:47 +00:00

Shorten README

jonashub referenced this issue from docs/quick-docs

2026-06-02 17:50:44 +00:00

Shorten README #973

jonashub commented

2026-06-02 18:06:02 +00:00

Member

Here is a list of repos where I believe we should implement this:

Here I'm not completely sure:

Here is a list of repos where I believe we should implement this: - [x] https://forge.fedoraproject.org/docs/quick-docs - [x] https://forge.fedoraproject.org/docs/release-notes - [x] https://forge.fedoraproject.org/docs/team-docs - [x] https://forge.fedoraproject.org/docs/accounts-docs - [x] https://forge.fedoraproject.org/docs/beginners-guide Here I'm not completely sure: - [x] https://forge.fedoraproject.org/docs/site-frontpage - [x] https://forge.fedoraproject.org/docs/release-docs-home

pbokoc commented

2026-06-03 16:04:06 +00:00

Author

Owner

Yeah, let's do the latter three as well.

E: Sorry, not the Contributor's Guide, that's the archived one and we have team-docs already covered.

Actually I'll just move that into the graveyard.

Yeah, let's do the latter three as well. E: Sorry, not the Contributor's Guide, that's the archived one and we have team-docs already covered. Actually I'll just move that into the graveyard.

👍 1

jonashub referenced this issue from a commit

2026-06-03 19:48:24 +00:00

Shorten README

jonashub referenced this issue from docs/release-notes

2026-06-03 19:48:45 +00:00

Shorten README #402

jonashub referenced this issue from docs/team-docs

2026-06-03 20:09:52 +00:00

Shorten README #61

jonashub referenced this issue from docs/accounts-docs

2026-06-03 20:17:07 +00:00