Refactors documentation structure for clarity and consistency

Improves readability and maintainability of project documentation by standardizing formatting, reorganizing sections, and aligning contribution and archive entry guidelines. Enhances link formatting, summary placement, and neutral language usage to ensure clarity for contributors and users.
This commit is contained in:
Nick2bad4u 2025-05-30 19:55:03 -04:00
parent 075d4121e7
commit 8e7ae89920
2 changed files with 341 additions and 571 deletions

View file

@ -12,25 +12,30 @@ Go into a GitHub project's issues, and sort by "Most commented" or "Most reactio
## Adding new drama
A new drama entry can be added into the list in the short or extended format. Short entry consists of the single link:
A new drama entry should follow the standardized formatting style used in the main README. There are two main formats:
**Short entry:**
```
[user/repo/issues/1](https://github.com/user/repo/issues/1)
- [user/repo/issues/1](https://github.com/user/repo/issues/1)
```
Extended entry can contain drama summary and one or more links:
**Extended entry:**
```
user/repo - Drama title
* Summary line 1
* Summary line 2
* [issues/1](https://github.com/user/repo/issues/1)
* [issues/2](https://github.com/user/repo/issues/2)
* [Other link text](https://example.com/other-link-url/)
### owner/repo
- [owner/repo/issues/123](https://github.com/owner/repo/issues/123) (archive: [1](https://archive.ph/abcde), [2](https://archive.ph/abcde), [3](https://archive.ph/abcde))
- Brief summary of the drama, written in a neutral tone.
- Additional context or summary lines as needed.
- Journalistic Media:
- [Media Outlet Title](https://media.example.com/article) (archive: [1](https://archive.ph/xyz), [2](https://web.archive.org/web/20230101000000/https://media.example.com/article))
```
## Writing guidelines
- If there are non-github links that describe the drama, consider adding them. High priority external links to add are articles in popular journalistic media.
- Adding drama summary is not mandatory. In the simplest case the entry can just consist of the single link to the dramatic thread. Summary can be helpful when there are multiple links that need to be logically grouped to better understand the drama.
- When drama summary is added, it must be as neutral as possible. Describe facts and events, but **do not** assess drama participants' actions, advocate for any political/ideological views, or use a negative speech. When in doubt, leave out any details and make summary as short as possible.
**Formatting guidelines:**
- Use `### owner/repo` as the section heading.
- List all relevant GitHub issues, pull requests, or discussions as bullet points, with archive links in the format `(archive: [1](...), [2](...), [3](...))` if available.
- Place the summary and context below the links, not above.
- If there are journalistic or media articles, add a `Journalistic Media:` section with links and archives at the bottom.
- Write summaries in a neutral, factual style, avoiding personal opinions or advocacy.
- Replace political or sensitive subjects with: ***⚠️ Sensitive Topic***

879
README.md

File diff suppressed because it is too large Load diff