Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[📑 Docs]: Reorganize documents in the community repo #1650

Open
1 task done
bandantonio opened this issue Jan 18, 2025 · 3 comments
Open
1 task done

[📑 Docs]: Reorganize documents in the community repo #1650

bandantonio opened this issue Jan 18, 2025 · 3 comments
Labels
📑 docs

Comments

@bandantonio
Copy link
Contributor

What Dev Docs changes are you proposing?

Based on the initial discussion in #1638 (comment)

According to the selected documentation projects for the Mentorship Program 2024, mentees will be working on adding new and expanding the existing guides. To keep the existing guides untouched and preserve original context and cross-linking, mentees will create updated versions of the guides that will eventually be merged with the "original ones".
For example, the original guide on how to (Become Maintainer in Existing Project and the updated one submitted in #1638. that

It would be beneficial to reorganize all the existing documents within the community project along with the guides that are going to be created because this will simplify accessibility, discoverability, and navigation. For now, in some cases, at least I am having hard times finding the proper guide even when I know that it must be somewhere near.

Possible implementation:

  • Brainstorm possible reorganization variants
  • Create a page or section with a clear navigation that would act as a single entry point for all the contribution-related documents within the repo.
  • Ensure the info in the documents is still relevant
  • Update cross-linking

Code of Conduct

  • I agree to follow this project's Code of Conduct
@bandantonio bandantonio mentioned this issue Jan 18, 2025
Open
14 tasks
@thulieblack thulieblack mentioned this issue Jan 31, 2025
Open
@bandantonio
Copy link
Contributor Author

After spending some time reviewing and the existing structure and documents, below is a list of inconsistencies that were found, along with a new proposed structure.

Legend

  • 🟩 - no changes required
  • 🟨 - changes required (for example, split, rename, or refactor)
  • 🟧 - changes that need review or validation

Governance and Policies

Project Vision and Strategy

  • 🟥 ROADMAP
    • 🟥 Must be created according to the p.3 of the Mission and Scope of the Project section in Charter

Community

  • 🟧 [Glossary of terms] - may it be useful to mention all the important terms like "contributor", "committer (voter)", "maintainer (code owner)", etc in one place?

Goals

Contribution Guidelines

  • 🟨 CONTRIBUTING
    • 🟨 Describes policies and processes for contributing
    • 🟨 Refactor it to make separate sections on:
      • (1) merging/blocking a PR as a code owner and
      • (2) merging a PR as a contributor
      • (3) listing PR Prerequisites for a successful merge
      • (4) using slash commands in comments section to manage PRs
  • 🟧 CODEOWNERS
    • 🟧 I believe it should be listed according to the p. 4 of the Committers and Contributors section in CHARTER
  • 🟨 recognize-contributors
    • 🟨 Merge into CONTRIBUTING as a new section
  • 🟨 contribute-blog-post
    • 🟨 Merge into CONTRIBUTING as a new section
  • 🟨 Become-maintainer-in-existing-project
    • 🟨 Make the doc more clear in its purpose (lots of confusion: tsc, maintainer, contributor, etc)
    • 🟨 Potentially a how-to guide (needs a separate section)
  • 🟨 git-workflow
    • 🟨 Merge into Become-maintainer-in-existing-project
  • 🟨 donating-projects
    • 🟨 Better file name to be more explicit?: donating-projects-to-asyncapi or donating-projects-to-organization

Documentation

Globally, I feel like all the documentation can be structured around three major files:

  • Where to contribute
  • How to contribute

Where to contribute - all the entry points and areas where contributors can help with their improvements, ideas, and expertise. This section should include information that is currently scattered across these docs:

This part can also organically include general information on the contributor's "growth" path from a first-time contributor to maintainer, ambassador, and eventually becoming a TSC member. Going through this path requires a contributor to be active and consistent with the contribution processes. So, there is a kind of gamification involved too, that's what can keep contributors motivated and engaged.

How to contribute - all the documents that clearly describe how to start contributing from the ground-up, including prerequisite knowledge, procedures, tools, till making PRs and merging them properly. This section should include information that is currently scattered across these docs:

Another part on how to contribute is to describe participation in mentorship programs. So the section will include all the info from the Mentorship Programs.

All this information can be added to the docs/onboarding-guide/index

Below are fragments of possible structure

Mentorship Programs

Meetings and Communication

  • 🟨 MEETINGS_ORGANIZATION
    • 🟨 Add spoilers to instructions
    • 🟨 Add ToC
    • 🟨 Make every Q&A more distinctive visually
  • 🟩 WORKING_GROUPS
  • 🟧 slack-etiquette
    • Guidelines for using Slack within the community.
  • 🟩 TWEET_TOGETHER
  • 🟧 [Social media communication guidelines]
    • Inspired by TWEET_TOGETHER. Do we need it rn?

Templates and Scripts

🟧 can they be potentially optimized with any of Discussion category forms?

@bandantonio
Copy link
Contributor Author

bandantonio commented Feb 10, 2025 •
edited
Loading

Proposed structure

Warning

This structure may be updated after the introduction of the Governance Board in #1634

.
├── CONTRIBUTING
└── docs/
    ├── CODE_OF_CONDUCT
    ├── FUNDING
    ├── GOVERNANCE
    ├── /governance-and-policies/
    │   ├── CHARTER
    │   ├── TSC_MEMBERSHIP
    │   └── TSC_VOTING_OVERVIEW
    ├── /project-vision-and-strategy/
    │   └── ROADMAP
    ├── /community/
    │   └── Glossary
    ├── /goals/
    │   └── annual-goals/2025_Community_Goals
    ├── /contribution-guidelines/
    │   ├── CODEOWNERS
    │   ├── recognize-contributors
    │   ├── contribute-blog-post
    │   ├── Become-maintainer-in-existing-project
    │   ├── git-workflow
    │   └── donating-projects
    ├── /guides/
    │   ├── repository-settings
    │   ├── new-tool-documentation
    │   ├── /onboarding/
    │   ├── Where to contribute
    │   └── How to contribute
    ├── /mentorship-program/
    │   ├── asyncapi mentorship
    │   ├── season of docs
    │   ├── summer of code
    │   └── winter of code
    ├── /meetings-and-communication/
    │   ├── MEETINGS_ORGANIZATION
    │   ├── WORKING_GROUPS
    │   ├── slack-etiquette
    │   ├── TWEET_TOGETHER
    │   └── social-media-communication-guidelines
    └── /templates-and-scripts/
        ├── .github/workflows/create-event-helpers/issues_templates/thinking-out-loud
        ├── .github/workflows/create-event-helpers/issues_templates/community
        ├── .github/workflows/create-event-helpers/issues_templates/spec-3-0
        ├── .github/workflows/create-event-helpers/issues_templates/lets-talk-about-contrib
        ├── .github/workflows/create-event-helpers/issues_templates/spec-3-docs
        ├── .github/workflows/create-event-helpers/issues_templates/ad-hoc
        ├── .github/workflows/scripts/README
        ├── .github/workflows/slack/README
        └── .github/scripts/maintainers/README

@thulieblack
Copy link
Member

Woow I need time to digest this @derberg

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
📑 docs
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@bandantonio @thulieblack