community icon indicating copy to clipboard operation
community copied to clipboard
verified publisher icon asyncapi

[📑 Docs]: Reorganize documents in the community repo

Open bandantonio opened this issue 1 year ago • 11 comments

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

  • [x] I agree to follow this project's Code of Conduct

bandantonio avatar Jan 18 '25 00:01 bandantonio

(Update from Mar 18)

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
  • 🟥 - Critical change that must be considered/implemented

[!IMPORTANT] Open Questions and todos

  1. If a need to have a more nested structure arises, we have to introduce another docs section like /community/docs with a similar structure as /docs.
  2. ✅ ~~TWEET_TOGETHER - agree with the marketing working group, is it still relevant?~~

Governance and Policies

  • 🟩 CHARTER
  • 🟨 TSC_MEMBERSHIP
    • 🟨 Split into "Technical Steering Committee (TSC) Overview" (covered in PR #1547) and "TSC Membership"
    • 🟨 Ensure that all the members are active voters - remove inactive to comply with the p.11 of the CHARTER. (see Emeritus.yaml)
  • 🟨 GOVERNANCE
    • 🟥 Lacks a list of Contributors and Committers. The Committers list must be referenced in the VOTERS file as well.
    • 🟥 Must include an overview of the voting process, which means that the existing voting file must be deprecated
  • 🟨 TSC_VOTING_OVERVIEW
    • 🟨 Should be renamed to VOTERS (info on voters: /tsc or voteTrackingFile.json ← to be created)
  • 🟥 voting
    • 🟥 MUST BE DEPRECATED according to the p.5 of the Voting section in CHARTER
  • 🟩 CODE_OF_CONDUCT
    • 🟨 code_of_conduct/code-of-conduct-committee
      • 🟨 Review broken links
    • 🟨 code_of_conduct/coc-incident-resolution-procedures
      • 🟨 Review for actuality and clarity
  • 🟧 PROJECT_FINANCE
    • 🟧 Rename to FUNDING.md or PROJECT_FUNDING.md? As sponsor button on GitHub is defined in FUNDING.yml file
  • 🟨 how-changes-in-the-spec-are-introduced
    • 🟨 Rename to "Introduction of changes to the Spec"

Project Vision and Strategy

  • 🟥 ROADMAP
    • 🟥 Must be created according to the p.3 of the Mission and Scope of the Project section in Charter
    • Review comment: Topic for discussion for the governance board, more likely a responsibility of the working groups

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?
    • Review comment: Glossary should address two types of contribution guides, considering maintainers, committers, triagers, etc. In some repos we we have pretty clear structure. It's either you're a Maintainer or not, and Maintainer is doing everything. Committer and Triager and everything. But in some repos, like website, we have 2 different types of maintainers, maintainers that can commit so they're committers, approvers, and we also have triagers. In Modelina we have a model of champions and the same we have in spec. that's also worth documenting globally, because then it's also a motivation for other maintainers of other projects to show how they can change and scale, because that's the goal of triagers and committers to scale the Maintainers group in a more complex project.

Goals

Contribution Guidelines

[!NOTE] There should be an explanation on how to figure out who's the maintainer of a given repo linking to CODEOWNERS file.

  • 🟨 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 these 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
  • 🟥 TWEET_TOGETHER Stale. Will be deprecated. Agreed with community and marketing representatives.
  • 🟨 [Social media communication guidelines] - to be created. Agreed with community and marketing representatives.

Templates and Scripts

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

  • .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

bandantonio avatar Feb 10 '25 21:02 bandantonio

Proposed structure (Deprecated, see the updated version)

[!CAUTION] This version of the structure is outdated and kept only to show the progression of iterations

[!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

bandantonio avatar Feb 10 '25 21:02 bandantonio

Woow I need time to digest this @derberg

thulieblack avatar Feb 11 '25 16:02 thulieblack

Okay, so my thoughts:

  1. The Code of Conduct can be on the root, not under docs
  2. Meeting doc must be spilt into 3 parts: one for meetings, restream onboarding, and podcast workflow explanation.
  3. I think the tweet should be depreciated.
  4. We need another folder under docs for the new onboarding guides being written by mentees, but I see you already added this

thulieblack avatar Mar 04 '25 13:03 thulieblack

https://github.com/user-attachments/assets/8693727c-8c90-4ef7-af62-4abc80736429

Transcriptiom:

WEBVTT

1
00:00:03.180 --> 00:00:12.520
Lukasz Gornicki: Hey? So I decided to record the the feedback cause. There's too many different things related.

2
00:00:14.970 --> 00:00:16.920
Lukasz Gornicki: So yeah, 1st of all,

3
00:00:18.561 --> 00:00:22.110
Lukasz Gornicki: congrats on doing this great work.

4
00:00:22.250 --> 00:00:25.969
Lukasz Gornicki: I can imagine there was a lot of things to to go through.

5
00:00:27.250 --> 00:00:33.280
Lukasz Gornicki: So 1st things, 1st code of conduct so code of conduct

6
00:00:33.470 --> 00:00:36.769
Lukasz Gornicki: as a file from the root. We cannot move it under docs.

7
00:00:37.330 --> 00:00:42.910
Lukasz Gornicki: We cannot move it under docs, because that's how, because of the of Github.

8
00:00:43.410 --> 00:00:49.360
Lukasz Gornicki: So basically, Github have this concept of community health files

9
00:00:49.620 --> 00:01:01.340
Lukasz Gornicki: and the community health files are like contributing Md, and or exactly code of conduct or license

10
00:01:02.460 --> 00:01:04.294
Lukasz Gornicki: that we don't have here, because,

11
00:01:05.720 --> 00:01:07.989
Lukasz Gornicki: there's no license. But we should have license.

12
00:01:08.410 --> 00:01:11.319
Lukasz Gornicki: But yeah, it's different topic. And if you have them

13
00:01:11.590 --> 00:01:14.845
Lukasz Gornicki: like license and other stuff. Then look

14
00:01:15.820 --> 00:01:24.930
Lukasz Gornicki: For example, it figures out, what's your code of conduct, for example, because it's in the root, and also

15
00:01:25.700 --> 00:01:27.819
Lukasz Gornicki: the thing is that it's so.

16
00:01:28.410 --> 00:01:33.929
Lukasz Gornicki: It's like with Readme. Md. It's such a standard now in the community in open source

17
00:01:34.260 --> 00:01:38.809
Lukasz Gornicki: that people always look for code of conduct, readme and contributing Md. In the root.

18
00:01:42.360 --> 00:01:46.710
Lukasz Gornicki: but but we still need it. So I mean, we still need it. I mean that

19
00:01:48.120 --> 00:01:50.309
Lukasz Gornicki: code of conduct should not be in the repo only

20
00:01:50.610 --> 00:01:54.559
Lukasz Gornicki: in the end it should be under docs and published on the website.

21
00:01:55.920 --> 00:02:00.150
Lukasz Gornicki: So how we do it.

22
00:02:01.380 --> 00:02:02.530
Lukasz Gornicki: It's different thing.

23
00:02:02.750 --> 00:02:06.827
Lukasz Gornicki: We need to probably automation like

24
00:02:07.680 --> 00:02:13.560
Lukasz Gornicki: maybe we need to extend the automation and have some custom scripts that like, take code of conduct from the root

25
00:02:14.880 --> 00:02:20.039
Lukasz Gornicki: and dynamically put it in docs, just like we do some changes with the with the other folders.

26
00:02:21.360 --> 00:02:28.040
Lukasz Gornicki: But yeah, for sure, it cannot be moved away from the root of the folder, funding and

27
00:02:30.900 --> 00:02:32.990
Lukasz Gornicki: funding funding. What's that?

28
00:02:52.622 --> 00:02:53.830
Lukasz Gornicki: Project finance? Okay?

29
00:02:57.487 --> 00:03:00.619
Lukasz Gornicki: yeah, I don't. I don't really mind

30
00:03:00.810 --> 00:03:03.816
Lukasz Gornicki: much about the name of the file in the end. It's

31
00:03:05.610 --> 00:03:10.339
Lukasz Gornicki: like in the end. Remember, it doesn't really matter what's defined names here.

32
00:03:12.820 --> 00:03:15.390
Lukasz Gornicki: As in the end the goal is to have it.

33
00:03:24.620 --> 00:03:26.189
Lukasz Gornicki: What's up of my network?

34
00:03:26.650 --> 00:03:28.170
Lukasz Gornicki: Yeah, to have it.

35
00:03:30.550 --> 00:03:38.150
Lukasz Gornicki: Wow, okay, to have it here. Right? So if

36
00:03:40.160 --> 00:03:48.560
Lukasz Gornicki: so, like basically the title matters, and then the the file name is only used in the

37
00:03:49.040 --> 00:03:51.619
Lukasz Gornicki: in the URL, if it's called funding, that's fine.

38
00:03:53.020 --> 00:04:05.329
Lukasz Gornicki: But yeah, definitely funding funding should be somewhere on the website.

39
00:04:05.520 --> 00:04:09.287
Lukasz Gornicki: Just a matter of like making sure we don't duplicate with

40
00:04:10.890 --> 00:04:17.649
Lukasz Gornicki: with finance, because we have some content in the finance. So that would have to be reviewed if we don't duplicate.

41
00:04:18.220 --> 00:04:21.648
Lukasz Gornicki: But probably the best would be if everything is under finance.

42
00:04:22.700 --> 00:04:33.499
Lukasz Gornicki: now, governance. But again, content is separate governance definitely. But then it's all under one folder, right? So this governance could also be there

43
00:04:34.310 --> 00:04:38.330
Lukasz Gornicki: under one like a.

44
00:04:39.580 --> 00:04:48.109
Lukasz Gornicki: we don't need. Basically, we don't need separate file like it can be. If in navigation we have the whole group called Governance. I think that's the best. We don't have to have individual

45
00:04:48.280 --> 00:04:49.010
Lukasz Gornicki: document.

46
00:04:49.310 --> 00:04:52.429
Lukasz Gornicki: So I would move this under under that

47
00:04:52.820 --> 00:05:01.990
Lukasz Gornicki: voting overview and voting summary. Also, I think we have voting overview or

48
00:05:05.150 --> 00:05:07.449
Lukasz Gornicki: yeah, voting overview. Sorry. Yeah, it's good.

49
00:05:09.450 --> 00:05:12.830
Lukasz Gornicki: Now, the roadmap I don't think we have.

50
00:05:14.640 --> 00:05:16.110
Lukasz Gornicki: That's fine, do we?

51
00:05:18.780 --> 00:05:21.460
Lukasz Gornicki: Oh, yeah, the new one, right? That's what you mean.

52
00:05:21.990 --> 00:05:25.299
Lukasz Gornicki: I know this one. That's a that's a crop.

53
00:05:25.830 --> 00:05:27.429
Lukasz Gornicki: Nobody's looking into it.

54
00:05:29.680 --> 00:05:37.720
Lukasz Gornicki: Yeah, it's a totally separate topic. I think we should. Basically, we should probably remove it

55
00:05:39.909 --> 00:05:46.519
Lukasz Gornicki: or at least have a discussion about it, like a totally separate discussion for a new governance board.

56
00:05:51.960 --> 00:05:59.160
Lukasz Gornicki: But but yes, vision and strategy for me. It's not the same as roadmap, or

57
00:06:00.440 --> 00:06:04.370
Lukasz Gornicki: we can have a vision. We can have a strategy that's for sure.

58
00:06:06.440 --> 00:06:12.259
Lukasz Gornicki: and we can have vision for marketing. We can have vision for community, we can have vision for other parts.

59
00:06:13.030 --> 00:06:19.540
Lukasz Gornicki: even as a part of the vision for us. And EPA. It could be a separate document, where we talk about the transparency, etc.

60
00:06:20.460 --> 00:06:24.089
Lukasz Gornicki: And and strategy, cooperation with other communities, etc.

61
00:06:24.980 --> 00:06:27.689
Lukasz Gornicki: And but and roadmap is just one of many

62
00:06:28.370 --> 00:06:33.440
Lukasz Gornicki: really not important documents. In my opinion the roadmap

63
00:06:34.270 --> 00:06:38.299
Lukasz Gornicki: should not be defined like in the past. It was executive director, which was from.

64
00:06:39.300 --> 00:06:46.389
Lukasz Gornicki: and then others could contribute the the ideal world is if the roadmap comes from the working groups.

65
00:06:47.670 --> 00:06:52.360
Lukasz Gornicki: So if somebody would like to have on the roadmap item like.

66
00:06:55.730 --> 00:07:06.099
Lukasz Gornicki: I don't know, like good coverage of code generation. So some technical item on the roadmap, then yeah, sure do it. But let's form a working group. Let's work together

67
00:07:08.230 --> 00:07:13.290
Lukasz Gornicki: and set up the world map and commit to the roadmap without working groups.

68
00:07:14.220 --> 00:07:15.350
Lukasz Gornicki: Setting roadmap.

69
00:07:15.770 --> 00:07:16.490
Lukasz Gornicki: Yeah.

70
00:07:16.700 --> 00:07:22.929
Lukasz Gornicki: Doesn't make much sense community glossary. Not sure about it.

71
00:07:26.010 --> 00:07:27.709
Lukasz Gornicki: That's something new, I guess.

72
00:07:29.060 --> 00:07:33.860
Lukasz Gornicki: Yes, yeah, we need glossary especially that we have 2 types of contributing guides.

73
00:07:34.400 --> 00:07:38.695
Lukasz Gornicki: We should also probably maybe address it within the same topic cause

74
00:07:40.080 --> 00:07:46.200
Lukasz Gornicki: because in some repos we we have pretty clear structure. It's either you're a Maintainer or not.

75
00:07:46.730 --> 00:07:52.279
Lukasz Gornicki: and Maintainer is doing everything. Committee is a Committer and Triager and everything.

76
00:07:52.590 --> 00:08:00.220
Lukasz Gornicki: But in some repos, like website, we have 2 different types of maintainers, maintainers that can commit and their committers approvers.

77
00:08:00.540 --> 00:08:02.889
Lukasz Gornicki: And we also have try azures.

78
00:08:04.850 --> 00:08:09.660
Lukasz Gornicki: So the closer you would have to address both different

79
00:08:10.120 --> 00:08:11.970
Lukasz Gornicki: models we have. We also have

80
00:08:12.790 --> 00:08:20.630
Lukasz Gornicki: in Modelina. We have a model of champions, and the same we have in spec, I think.

81
00:08:21.670 --> 00:08:28.999
Lukasz Gornicki: And again, that's also worth documenting globally, because then it's also a motivation for other maintainers of other projects like

82
00:08:29.670 --> 00:08:34.110
Lukasz Gornicki: to show how they can change and scale, because, like.

83
00:08:34.820 --> 00:08:42.879
Lukasz Gornicki: basically, that's the goal of try azure and committer to scale the Maintainers group in a more complex project.

84
00:08:44.590 --> 00:08:45.630
Lukasz Gornicki: Goals.

85
00:08:49.210 --> 00:08:50.730
Lukasz Gornicki: I think.

86
00:08:55.190 --> 00:08:59.590
Lukasz Gornicki: if not part of this, at least next to this

87
00:09:02.910 --> 00:09:07.560
Lukasz Gornicki: vision and goals, yeah, community goals.

88
00:09:08.920 --> 00:09:18.520
Lukasz Gornicki: And I wouldn't do also that nested in a nested structure pretty flat, I would say, under one folder.

89
00:09:19.510 --> 00:09:25.260
Lukasz Gornicki: where probably we can have vision, strategy and goals in one. I would suggest, not split.

90
00:09:25.430 --> 00:09:33.430
Lukasz Gornicki: So it's much easier to navigate guidelines. Yes. Blah, blah.

91
00:09:39.536 --> 00:09:40.069
Lukasz Gornicki: come in

92
00:09:49.490 --> 00:09:50.530
Lukasz Gornicki: 19.

93
00:09:52.200 --> 00:09:53.030
Lukasz Gornicki: It's here

94
00:10:04.470 --> 00:10:06.879
Lukasz Gornicki: here, I thought. It's on the website.

95
00:10:15.300 --> 00:10:19.890
Lukasz Gornicki: We only have technical instruction here. Okay, cool, nice.

96
00:10:21.070 --> 00:10:23.290
Lukasz Gornicki: fact. That's a really good research.

97
00:10:25.760 --> 00:10:27.990
Lukasz Gornicki: Become maintainer and existing.

98
00:10:28.970 --> 00:10:35.790
Lukasz Gornicki: Yeah, basically like, donating projects, like all everything contribution guidelines.

99
00:10:40.210 --> 00:10:41.599
Lukasz Gornicki: This. Yes.

100
00:10:43.220 --> 00:10:50.170
Lukasz Gornicki: This. Not sure. If it's not part of governance, because it's a more.

101
00:10:50.270 --> 00:10:52.059
Lukasz Gornicki: It's not like, I mean, it's

102
00:10:52.180 --> 00:11:00.050
Lukasz Gornicki: okay. You can say it's somebody donating is basically contributing a project. But don't know

103
00:11:02.170 --> 00:11:04.119
Lukasz Gornicki: probably better if it's

104
00:11:07.310 --> 00:11:11.390
Lukasz Gornicki: because in the end it's also a governance of the project

105
00:11:16.320 --> 00:11:28.530
Lukasz Gornicki: unless we all contribution guidance, like my opinion, probably recognize contributions. Yes, co-owners, Co donors.

106
00:11:28.730 --> 00:11:31.649
Lukasz Gornicki: But this code owners is just technical.

107
00:11:43.950 --> 00:11:48.430
Lukasz Gornicki: Yeah, code owners. It's it's just code owners for the community repo so definitely

108
00:11:49.940 --> 00:11:55.699
Lukasz Gornicki: it cannot be moved as well. It's a technical Github feature.

109
00:11:57.710 --> 00:12:02.810
Lukasz Gornicki: All, every repo should have its own code owners that defines the code owner structure.

110
00:12:03.090 --> 00:12:08.420
Lukasz Gornicki: So this has to be in the root. But of course, in the contribution guide, it would be nice to have an explanation like

111
00:12:08.550 --> 00:12:11.609
Lukasz Gornicki: basically how to figure out who's the maintainer of a given repo?

112
00:12:11.920 --> 00:12:15.360
Lukasz Gornicki: It's from the code owners file. So this should be explained.

113
00:12:16.530 --> 00:12:28.590
Lukasz Gornicki: Recognize contributor contributors when contribute blog posts become maintaining existing project, it workflow and donating projects. Yeah.

114
00:12:30.190 --> 00:12:39.120
Lukasz Gornicki: yeah, I'm not 100% convinced. But also the governance. So yeah, guides, repository settings.

115
00:12:45.550 --> 00:12:47.819
Lukasz Gornicki: New tool documentation.

116
00:12:48.260 --> 00:12:54.200
Lukasz Gornicki: Yeah. Okay, new tool documentation onboarding

117
00:12:57.420 --> 00:13:01.390
Lukasz Gornicki: were to contribute how to contribute.

118
00:13:01.950 --> 00:13:07.249
Lukasz Gornicki: Yeah. So new tool documentation is pretty similar similar to

119
00:13:13.350 --> 00:13:16.309
Lukasz Gornicki: attribution is pretty similar to donation, as far as I know.

120
00:13:24.070 --> 00:13:26.299
Lukasz Gornicki: Oh, no. It's this one fuck. Yeah. Okay.

121
00:13:27.290 --> 00:13:31.150
Lukasz Gornicki: like, how to add tool to the to the website. Okay.

122
00:13:31.990 --> 00:13:34.231
Lukasz Gornicki: guides. Yeah, yeah, it's guide

123
00:13:38.240 --> 00:13:42.589
Lukasz Gornicki: on boarding, like, basically, we cannot do such nested structures.

124
00:13:43.040 --> 00:13:47.799
Lukasz Gornicki: So onboarding should be separate and pretty

125
00:13:48.380 --> 00:13:49.970
Lukasz Gornicki: up on the list, I would say.

126
00:13:50.160 --> 00:13:56.179
Lukasz Gornicki: because we want people like most of the people that will look into community docs, they will look on the onboarding. So

127
00:13:56.990 --> 00:14:01.839
Lukasz Gornicki: I would say, onboarding is a separate thingy and on the top.

128
00:14:02.860 --> 00:14:07.710
Lukasz Gornicki: And what I mean by nested structures is like basically on the Async Api doc

129
00:14:09.130 --> 00:14:12.740
Lukasz Gornicki: maximum we can do is tutorials

130
00:14:15.880 --> 00:14:17.800
Lukasz Gornicki: missed it, and that's it.

131
00:14:18.660 --> 00:14:22.479
Lukasz Gornicki: So community and nested, and that's it.

132
00:14:23.380 --> 00:14:32.330
Lukasz Gornicki: There's no technical solution for having nested nested like. So we have.

133
00:14:33.070 --> 00:14:39.209
Lukasz Gornicki: Let's say, 0 level 0 level one, and that's it.

134
00:14:40.620 --> 00:14:45.444
Lukasz Gornicki: So onboarding guide should probably be called document

135
00:14:49.140 --> 00:14:58.770
Lukasz Gornicki: I don't know. Documentation or technical writer onboarding guide. I don't know. Docs contributor Onboarding Guide for

136
00:14:58.960 --> 00:15:06.360
Lukasz Gornicki: Maintainers. It's separate so we can't. We cannot.

137
00:15:06.580 --> 00:15:08.160
Lukasz Gornicki: You can't do it like this.

138
00:15:11.280 --> 00:15:13.470
Lukasz Gornicki: That's how that's how it looks like

139
00:15:17.010 --> 00:15:18.340
Lukasz Gornicki: And that's why

140
00:15:19.190 --> 00:15:25.699
Lukasz Gornicki: we maybe have to like if we think it's gonna be like, basically, we're going to see if it's too much

141
00:15:30.900 --> 00:15:32.000
Lukasz Gornicki: under one.

142
00:15:32.520 --> 00:15:35.659
Lukasz Gornicki: Maybe not. But then, if you really want to have double.

143
00:15:36.550 --> 00:15:44.569
Lukasz Gornicki: then we need to forget about having community documentation under docs. And then, as we initially also discussed, maybe have it under community.

144
00:15:45.840 --> 00:15:54.419
Lukasz Gornicki: And then you start with like onboarding guide, like the overview becomes welcome.

145
00:15:54.770 --> 00:15:57.809
Lukasz Gornicki: Onboarding guide becomes like, let's say concept. And then you have

146
00:15:58.980 --> 00:16:03.579
Lukasz Gornicki: different onboarding guide groups and then onboarding guides for a given onboarding guide.

147
00:16:04.680 --> 00:16:09.239
Lukasz Gornicki: So basically, instead of Docs community, we have community

148
00:16:15.590 --> 00:16:17.420
Lukasz Gornicki: which, of course, doesn't exist.

149
00:16:19.720 --> 00:16:28.210
Lukasz Gornicki: That is easier to do than having more nested structures here, especially because of the usability.

150
00:16:28.630 --> 00:16:34.660
Lukasz Gornicki: But of course, like in the past, we had a long discussion about. Like should it be in under community or under talks?

151
00:16:35.650 --> 00:16:42.789
Lukasz Gornicki: I'm team community get. Suddenly she was part of Docs.

152
00:16:42.950 --> 00:16:51.829
Lukasz Gornicki: Oh, dear, we start stayed with docs. Maybe we should. Everything up to you folks.

153
00:16:52.200 --> 00:16:55.550
Lukasz Gornicki: Mentorship program. Yes, everything about mentorship under one.

154
00:16:59.270 --> 00:17:02.940
Lukasz Gornicki: We also have to have an ambassador program separately.

155
00:17:03.370 --> 00:17:12.700
Lukasz Gornicki: Meetings and communication meetings. Yeah, everything working groups. Working groups are more about governance.

156
00:17:14.207 --> 00:17:17.409
Lukasz Gornicki: I would say. It's like Tsc members.

157
00:17:19.829 --> 00:17:23.439
Lukasz Gornicki: That's the document documented in the charter.

158
00:17:26.420 --> 00:17:42.830
Lukasz Gornicki: And and yeah, working groups probably should be under the governance slug, a ticket meetings, meter

159
00:17:43.370 --> 00:17:44.270
Lukasz Gornicki: tweet together.

160
00:17:44.890 --> 00:17:46.390
Lukasz Gornicki: That should be.

161
00:17:46.670 --> 00:17:50.349
Lukasz Gornicki: I think it should be removed. Really, this functionality in general

162
00:17:51.050 --> 00:17:56.949
Lukasz Gornicki: social media communication, I think I created the issue for Rami for it.

163
00:18:57.700 --> 00:19:01.109
Lukasz Gornicki: Damn it, I was like almost 100% sure that it's.

164
00:19:02.010 --> 00:19:08.540
Lukasz Gornicki: And I created issues for it. Okay, anyway, nobody's really using it.

165
00:19:10.010 --> 00:19:14.540
Lukasz Gornicki: Social media. But yeah, it has to be, of course, agreed

166
00:19:14.840 --> 00:19:21.859
Lukasz Gornicki: with the marketing working group because it's the social media stuff communication guidelines.

167
00:19:28.370 --> 00:19:33.479
Lukasz Gornicki: Maybe we need section marketing, actually where the marketing strategy will be, etc.

168
00:19:35.580 --> 00:19:43.999
Lukasz Gornicki: So yeah, mind me, that we need separate marketing stuff templates and scripts.

169
00:19:51.560 --> 00:19:57.570
Lukasz Gornicki: No, no, no, no, this has to. Technically

170
00:19:58.750 --> 00:20:02.010
Lukasz Gornicki: they are. These are templates for issues.

171
00:20:02.390 --> 00:20:05.430
Lukasz Gornicki: for the automation of meetings organization.

172
00:20:05.980 --> 00:20:11.179
Lukasz Gornicki: So they have to stay where they are under Github workflow because they belong to the Ci CD.

173
00:20:11.540 --> 00:20:15.540
Lukasz Gornicki: Nobody should use them manually. They are purely for automation.

174
00:20:15.640 --> 00:20:19.309
Lukasz Gornicki: Actually, that's another stuff that has to be cleared out. And

175
00:20:20.130 --> 00:20:23.659
Lukasz Gornicki: this is not organized for over 2, 3 years should be removed.

176
00:20:24.590 --> 00:20:31.530
Lukasz Gornicki: There's a lot of cleanup in meetings organization really needed. This is really not organized anymore, because we have spec released

177
00:20:33.140 --> 00:20:34.830
Lukasz Gornicki: this same here.

178
00:20:36.210 --> 00:20:39.140
Lukasz Gornicki: So this 3 meetings actually should not be even

179
00:20:39.820 --> 00:20:49.220
Lukasz Gornicki: listed in any documentation and be removed from the website and the and everywhere scripts.

180
00:20:49.670 --> 00:20:58.820
Lukasz Gornicki: Scripts. There might be some good with me scripts.

181
00:21:05.240 --> 00:21:05.950
Lukasz Gornicki: Hmm!

182
00:21:21.033 --> 00:21:21.759
Lukasz Gornicki: No, no.

183
00:21:25.100 --> 00:21:30.400
Lukasz Gornicki: Yeah. That's coming from the automation from Dot Github. So that yeah, it's coming.

184
00:21:31.330 --> 00:21:35.610
Lukasz Gornicki: even if you remove it from here. It's going to be brought back by automation so that

185
00:21:36.890 --> 00:21:38.720
Lukasz Gornicki: this must stay where it is.

186
00:21:39.220 --> 00:21:41.160
Lukasz Gornicki: Now. Slack with me.

187
00:21:44.250 --> 00:21:44.920
Lukasz Gornicki: It's not.

188
00:21:59.580 --> 00:22:00.449
Lukasz Gornicki: That's a lot of

189
00:22:07.280 --> 00:22:09.113
Lukasz Gornicki: yeah. This could be like

190
00:22:12.550 --> 00:22:13.890
Lukasz Gornicki: like, basically.

191
00:22:14.010 --> 00:22:20.650
Lukasz Gornicki: we should have some documentation for slack. How slack is organized. So, for example, this is, as far as I remember, document that describes how the

192
00:22:20.920 --> 00:22:25.430
Lukasz Gornicki: integration with Slack, with slack works to get the groups in place like, you know.

193
00:22:25.640 --> 00:22:29.059
Lukasz Gornicki: people can call out maintainers of the website and slack, etcetera.

194
00:22:29.470 --> 00:22:34.080
Lukasz Gornicki: So that's pretty technical documentation for for the automation.

195
00:22:35.585 --> 00:22:44.530
Lukasz Gornicki: But it's not tapeless net scripts. It's more the automation, I would say, and maintainers with me.

196
00:22:45.880 --> 00:22:47.690
Lukasz Gornicki: It's the same, I guess.

197
00:22:51.600 --> 00:22:52.389
Lukasz Gornicki: Where was it?

198
00:22:53.330 --> 00:22:54.260
Lukasz Gornicki: Scripts meeting?

199
00:23:01.060 --> 00:23:04.390
Lukasz Gornicki: Yeah, it's it's matter of work. Yeah, yeah.

200
00:23:08.690 --> 00:23:12.849
Lukasz Gornicki: that's again, like, in case of the Slugger automation. That's the

201
00:23:14.520 --> 00:23:22.790
Lukasz Gornicki: documentation for how the automation works in case of the Maintainers Yama file.

202
00:23:23.400 --> 00:23:26.730
Lukasz Gornicki: So again, automation.

203
00:23:29.170 --> 00:23:33.135
Lukasz Gornicki: Yep, that's about it. So like,

204
00:23:40.310 --> 00:23:41.550
Lukasz Gornicki: yeah, that's it.

derberg avatar Mar 04 '25 13:03 derberg

I'll be submitting this issue to the Bounty Program

thulieblack avatar Mar 05 '25 08:03 thulieblack

Bounty Issue's service comment

Text labels: bounty/2025-Q2, bounty/advanced, bounty/docs First assignment to regular contributors: 2025-03-21 00:00:00 UTC+12:00 End Of Life after: 2025-04-30 23:59:59 UTC-12:00

@asyncapi/bounty_team

The Bounty Program is not a Mentorship Program. The accepted level of Bounty Program Participants is Middle/Senior.
Regular contributors should explain in meaningful words how they are going to approach the resolution process when expressing a desire to work on this Bounty Issue.

aeworxet avatar Mar 17 '25 13:03 aeworxet

The Bounty Issue will be assigned to @bandantonio

thulieblack avatar Mar 18 '25 11:03 thulieblack

Proposed structure v2.1 (Update from Mar 28)

The updated structure incorporates review feedback from @derberg

[!WARNING] This structure may be updated after the introduction of the Governance Board in #1634

Community Root
 ├── CONTRIBUTING
 ├── GOVERNANCE
 └── docs
     ├── CODE_OF_CONDUCT
     ├── CODE_OF_CONDUCT_COMMITTEE
     ├── COC-incident-resolution-procedures
     ├── CODEOWNERS
     ├── community-glossary
     ├── /000-onboarding/
     │   ├── Where to contribute
     │   ├── How to contribute
     │   ├── Documentarian Onboarding Guide
     │   ├── Maintainer Onboarding Guide
     │   └── ... (more onboarding guides)
     ├── /010-contribution-guidelines/
     │   ├── recognize-contributors
     │   ├── contribute-blog-post
     │   ├── Become-maintainer-in-existing-project
     │   └── git-workflow
     ├── /011-styleguide/
     │   └── ... (related docs)
     ├── /020-governance-and-policies/
     │   ├── CHARTER
     │   ├── PROJECT_FUNDING
     │   ├── TSC_MEMBERSHIP
     │   ├── TSC_VOTING_OVERVIEW
     │   ├── WORKING_GROUPS
     │   ├── donating-projects
     │   └── how-changes-in-the-spec-are-introduced
     ├── /030-project-vision-strategy-goals/
     │   ├── Community: Vision, Strategy, Goals
     │   ├── Marketing: Vision, Strategy, Goals
     │   ├── ... (related docs)
     │   └── ROADMAP
     ├── /040-guides/
     │   ├── repository-settings
     │   └── new-tool-documentation
     ├── /050-mentorship-program/
     │   ├── asyncapi mentorship
     │   ├── ambassador program
     │   ├── season of docs
     │   ├── summer of code
     │   ├── winter of code
     │   └── ... (related docs)
     ├── /060-meetings-and-communication/
     │   ├── MEETINGS_ORGANIZATION
     │   └── slack-etiquette
     └── /070-marketing/
         └── social-media-communication-guidelines

bandantonio avatar Mar 18 '25 23:03 bandantonio

@derberg Thank you very much for such a detailed review, I really appreciate your feedback. 🤝

I made changes to the high-level structure and tried to address the challenges you've mentioned (especially the one related to a technical limitation for nesting on the website - I didn't know it).

One of your concerns was about the location of community health files (like CODEOWNERS, CODE_OF_CONDUCT, CONTRIBUTING, etc). Partially, you were right, as some of them were indeed located too deep in the hierarchy (like CODEOWNERS, and GOVERNANCE), I fixed that. But according to the official docs: Creating a default community health file there are 3 allowed locations for these files:

  1. The .github folder
  2. The root of the repository
  3. The docs folder

Since placing certain health files into the docs folder doesn't prevent GitHub from retrieving these files and rendering them as usual, I decided to place them here to keep the root directory clean. I initially placed some of the files too deep into the structure Anyway, I have no objections in moving them all (or partially) back to the root folder if you think it's better to have them all in one place for better navigation and discovery. Please let me know what you think.

Your another concern was about having the CODE_OF_CONDUCT file both in the root and the docs folders to be rendered on the website. With the current structure, we can place it right in the docs folder and GitHub will render it as expected. If we decide to move it deeper into the structure (to find a better place to be rendered on the website), I believe, we can use symbolic link or some kind of partials/includes mechanism (I haven't checked the full potential of the website platform yet) to keep a single source of truth.

Also, you mentioned about placing some of the folders (like /onboarding/) close to the top of the parent docs folder. So, I introduced a numbered prefixes as the simplest solution to keep important folders in the desired order.

bandantonio avatar Mar 18 '25 23:03 bandantonio

Bounty Issue's Timeline

Complexity Level Assignment Date (by GitHub) Start Date (by BP Rules) End Date (by BP Rules) Draft PR Submission Final PR Merge Start Final PR Merge End
Advanced 2025-03-18 2025-04-07 2025-06-01 2025-04-27 2025-05-18 2025-06-01
Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.
Keep in mind the responsibility for violations of the Timeline.

Assignee: @bandantonio (githubID: 16765690)

aeworxet avatar Mar 20 '25 09:03 aeworxet

@bandantonio (githubID: 16765690), please provide an update to the PR of the Bounty Issue.

aeworxet avatar May 06 '25 12:05 aeworxet

@bandantonio (githubID: 16765690), please provide an update to the PR of the Bounty Issue.

aeworxet avatar May 13 '25 05:05 aeworxet

@aeworxet Done, the bounty issue is updated.

bandantonio avatar May 13 '25 06:05 bandantonio

@bandantonio (githubID: 16765690), please provide an update to the PR of the Bounty Issue.

aeworxet avatar May 20 '25 07:05 aeworxet

Please, can we have an extra week or two to complete the review from the code owners' end?

thulieblack avatar May 30 '25 08:05 thulieblack

Upon request of the AsyncAPI Maintainer, who is responsible for the resolution of the Bounty Issue from the AsyncAPI's side (@thulieblack (githubID: 66913810)), all remaining target dates of the Bounty Issue's Timeline are extended by two calendar weeks.

Bounty Issue's Timeline Extended

Complexity Level Assignment Date (by GitHub) Start Date (by BP Rules) End Date (by BP Rules) Draft PR Submission Final PR Merge Start Final PR Merge End
Advanced 2025-03-18 2025-04-07 2025-06-15 2025-04-27 2025-05-18 2025-06-15
Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.
Keep in mind the responsibility for violations of the Timeline.

Assignee: @bandantonio (githubID: 16765690)

aeworxet avatar May 30 '25 10:05 aeworxet

This bounty issue is complete

thulieblack avatar Jun 10 '25 11:06 thulieblack

Bounty Issue Is Completed 🎉

@bandantonio (githubID: 16765690), please go to the dedicated AsyncAPI Bounty Program 2025-Q2 page on Open Collective and submit an invoice for USD 400.00 (button 'ACTIONS', dropdown option 'Submit expense') with the expense title Bounty community#1650, tag bounty, and full URL of this Bounty Issue in the description.

After submitting the invoice, please post the link to it in this Bounty Issue as a separate comment.

aeworxet avatar Jun 10 '25 11:06 aeworxet

@bandantonio (githubID: 16765690), please post the link to the invoice on Open Collective in this Bounty Issue as a separate comment to verify the invoice's authorship.

aeworxet avatar Jun 12 '25 23:06 aeworxet

@aeworxet https://opencollective.com/asyncapi/projects/asyncapi-bounty-program/expenses/253309

bandantonio avatar Jun 13 '25 09:06 bandantonio

bandantonio https://opencollective.com/asyncapi/projects/asyncapi-bounty-program/expenses/253309

✅ The invoice https://opencollective.com/asyncapi/projects/asyncapi-bounty-program/expenses/253309 was submitted by @bandantonio (githubID: 16765690), who was the AsyncAPI Bounty Program 2025-Q2 Participant and completed the Bounty Issue community#1650.

aeworxet avatar Jun 13 '25 12:06 aeworxet