1This is a response to a
2[reddit thread](https://old.reddit.com/r/opensource/comments/1mfr21t/experienced_developer_trying_open_source_for_the/).
3
4- Author: Daniel (ficd).
5- This document is dedicated to the public domain.
6
7## preface
8
9I'll just preface by saying that my policy is honesty --- if anything comes off
10as rude, that's not my intention. I'm always happy to see people actually asking
11questions and engaging. All too often, there's folks that come barging in with
12vibe--coded slop that doesn't solve any real problem, then act entitled to our
13(FOSS community) attention and feedback. You don't seem to be doing the latter,
14which makes me feel comfortable writing a thoughtful response knowing it won't
15be totally ignored; I have no expectation that you will agree with any of what I
16say (I am quite opinionated), but I have a feeling you'll at least read and
17consider it :)
18
19## not all about building community
20
21With that being said, I want to point out that being part of a community and
22contributing to a project is a different thing from developing your own project.
23In the latter case, I think you may be putting the cart in front of the horse.
24
25What I mean by this is that you seem to be pretty focused on building a
26community right off the bat. There's nothing wrong with that, but in my opinion
27it's the wrong priority. Pretty often there's posts around here asking about how
28to gain visibility, how to build a community, devs feeling demotivated because
29no one's using their project. It's the natural consequence of applying a
30"corporate" or "side--project hustle culture" type of mindset to open source ---
31but I feel like it fundamentally misunderstands what we're all doing here.
32
33There aren't many people going around hunting for "projects to contribute to".
34People will naturally contribute to projects that they _use_ and that they
35_believe in_. Personally, when I come upon a brand--new project with barely any
36participation besides the maintainer, but the README or documentation website is
37chock--full of "how to contribute", "community guidelines", etc., it feels a tad
38disingenuous --- like the goal of building a community outweighs the goal of
39building good software. Not to imply that's always the case; but that's just the
40impression that I (and I imagine other developers) tend to get.
41
42I seriously don't think it's actually about having users or contributors. Let me
43offer some personal examples. I maintain many projects. Only one of them has
44users _that I know of for sure_. The others _might_ have users, but I don't
45actually know. I receive the occasional PR, issue, or email, which I address
46earnestly and move on.
47
48And yet, I don't feel any less "part of the community". You're still an
49open--source maintainer even if no one contributes. My biggest project so far, a
50custom SSG called [Zona](https://git.ficd.sh/ficd/zona), is on a self--hosted
51Git forge with closed registration, meaning I only accept contributions via
52`git send-mail` (in theory, since no one has tried yet). But I don't consider it
53to be any less worthy of a project, or myself to be any less of a maintainer
54just because of it. I _also_ don't think a project needs a super comprehensive
55community code of conduct, issue & PR templates, etc. to be accessible for
56contribution.
57
58## documentation matters a lot
59
60The _most_ important thing, **by far**, is good, _detailed_ documentation. You
61don't need "how to contribute" docs if you can explain well how every component
62of your project works, and _why_ it works that way. That's the kind of
63documentation that can equally benefit both users and potential contributors. In
64fact, most contributors start out as users -- and no one will end up
65contributing to a project they can't figure out how to use in the first place.
66
67Now, all of that said, considering your corporate background and your stated
68intent to "stop being a spectator", I think you're doing _very_ well. It can
69often feel like FOSS is being inundated with disingenuous people that just want
70to pad their resumes, and your project doesn't come off like that. Let me share
71_why_, as someone that's seen a _lot_ of garbage: the project addresses and
72solves a _real_ problem, one that feels personal and relatable. It doesn't seem
73like one of those "I built a FREE and OPEN SOURCE tool that does XYZ" (the tool
74in question is just a wrapper around ChatGPT API). This alone already gives you
75more credibility than half the people I see posting about their new projects.
76
77## answers
78
79Here's how I'd answer your questions:
80
81- How do you write issues that actually help newcomers contribute?
82 - Explain _precisely_ what the problem is, how it should be solved, and
83 perhaps include a starting point, like "the `module_name.foobar()` is the
84 likely culprit".
85- What's the etiquette around reviewing PRs from strangers?
86 - Be polite, but remember that this is your project, and you're under no
87 obligation to accept code that either 1. sucks ass, or 2. takes the project
88 in a direction you don't agree with.
89- How much roadmap should you have vs letting community drive direction?/How do
90 you balance your vision with community input?
91 - I genuinely believe that the best projects are led by opinionated developers
92 with a clear vision. I also don't think you need to worry about this until
93 you actually build a sizable community. Until then, this is _your_ project
94 with the occasional contributor.
95
96- What are the unwritten rules newcomers to open source should know?
97 - Do **not** act entitled. Maintainers are not required to review your PR or
98 Issue, _especially_ if it's low effort. Your project is not entitled to
99 feedback, review, users, or contributors. **Make people _want_ to do it
100 anyways.**
101 - Maintainers and other contributors are people too -- besides the obvious
102 "respect" point, this means that **they're capable of stupidity as much as
103 anyone else**. If a contributor is an asshole when reviewing your PR,
104 _ignore them_. If a maintainer dismisses _valid_ concerns with an attitude
105 and without justification, _don't bother_. If it's that important, fork the
106 project. This is why `basedpyright` exists.
107 - It's OK to fork. Don't feel pressured to _always_ contribute upstream and
108 water down your changes as a result. If your change is _really_ that
109 important, and it's not being accepted (sometimes for perfectly valid
110 reasons!) then it's OK to fork!
111 - Licenses matter, and should be chosen intentionally. Don't just slap MIT on
112 everything, really consider "what license makes sense for what I'm
113 building?"
114 - People that are here _just for the sake of being here_ (resume padding,
115 clout, validation, whatever) will not be taken seriously. Of course, people
116 that are _learning_ or pivoting into FOSS are very welcome; the key is
117 transparency and sincerity, not pretense.
118 - There's nothing wrong with building something open source that _integrates_
119 with something proprietary; just be upfront about it. If your tool heavily
120 relies on, say, proprietary APIs or has a proprietary dependency, and that's
121 not stated upfront, people will feel tricked.
122- How do you evaluate if a small project is worth other people's time?
123 - Is it worth _your_ time? If someone completely different were writing this
124 project, would _you_ care?
125- Any red flags that scream "this person doesn't understand open source
126 culture"?
127 - Way too much emphasis is put on it being "FREE and OPEN SOURCE" in the
128 readme, the Reddit posts sharing it, etc.
129 - This _always_ feels like people that couldn't care less about the FOSS
130 community are cashing in for portfolio points. It just feels so _icky_. If
131 you're posting in r/opensource, then _obviously_ your shit is
132 open--source. There's also this underlying assumption that just _because_
133 the project is open source, it's somehow entitled to our attention,
134 feedback, etc.
135 - Learning projects that **advertise themselves as something they're not**.
136 - There's absolutely nothing with creating something impractical or
137 reinventing the wheel for your own learning or fun. But _please_ don't kid
138 yourself and say some shit like "the new CLI native todo app developers
139 have been waiting for!!!"
140 - README is infested with emojis (like, one emoji per bullet point). Sure,
141 this isn't always a reliable heuristic or indicative of low--effort, but
142 first impressions matter a lot, so it's better to err on the side of caution
143 here.
144 - If documentation is obviously AI--generated. There's no clear heuristic for
145 this, but... from what I've seen, if it walks like a duck...
146 - The "documentation website" is way too fancy, and sometimes more polished
147 than the project itself
148 - There's a "buy me a coffee" button on a project that clearly took minimal
149 effort to create
150 - The documentation makes assumptions about your OS:
151 - When a project bills itself as being "cross--platform", but the readme
152 only has installation instructions for Windows, immediate red flag --- now
153 I know this likely hasn't been tested on any other platform.
154 - Linux instructions assume Ubuntu/Debian and are not generic
155 - Junk is checked into the repo (may seem obvious, but I saw a "FREE and OPEN
156 SOURCE" project with `__pycache__` checked in the other day)
157 - (I'm likely to give the above more grace than when I see a `.cursor` or
158 equivalent checked in -- if you couldn't be bothered to code it yourself,
159 why on _**Earth**_ should I consider using it? Giving "feedback" on a
160 project you didn't build?)
161
162The above list isn't comprehensive by any means, and I'm sure folks will have
163disagreements as well.
164
165## readme feedback
166
167In terms of specific feedback on your README:
168
169- In the prelude section, I'd separate _what_ the extension does, and _why_ into
170 separate sentences or paragraphs. For example, "TuringOff (...) blocks AI
171 chatbot websites by doing X, Y, and Z. Our goal is to encourage (...)"
172- Describing the blocking message as "humorous" in the documentation itself
173 feels a bit conceited. You can't really make an assumption that people will
174 find it funny; and frankly, the block page being "funny" doesn't constitute a
175 feature. The fact that there _is_ a blocking page is worth mentioning, but I'd
176 word it differently.
177- I could do without the emojis on each heading, but at least you've kept them
178 tasteful. Be wary of emoji overuse though, it can smell of AI.
179- I recommend explaining the features in more detail in a separate section. For
180 example, it's not immediately clear what makes the AI detection "smart". An
181 explanation would go a long way in making your project more credible. Re:
182 lightweight; this means different things to different people. Some benchmarks
183 would be great to back that claim, and demonstrate that you've put in the
184 effort.
185- Installation instructions are great. Nitpick, but I'd change quotes like "Add
186 to Chrome" to inline code: `Add to Chrome`.
187- Usage instructions are good. Since the means of interaction is GUI, I think it
188 could benefit from some screenshots.
189- I'd get rid of the technical architecture section in the README. The "Key
190 Features" listed there don't seem like implementation details, they're
191 important selling points, so I think it's worth merging them with the features
192 listed at the top of page. For the components, I'd recommend creating a
193 separate `ARCHITECTURE.md`, moving them there, and then fleshing out that
194 document a lot more.
195- Perhaps pedantic, but I'd rename Customization to Configuration, since this
196 affects the actual core behavior of the extension.
197- Also, maybe I'm misunderstanding the extension, but wouldn't you need to
198 install the extension manually, or do some tinkering within your browser
199 profile to modify `background.js` and `messages.json`? If that's the case, I'd
200 make a note about that in the section because it's not immediately clear. For
201 example, can this be done on the fly, or does the tool need to be rebuilt
202 after changing one of those files?
203- Same applies to styling. Also, since this section is so short, I'd merge it
204 into the above.
205- I love that you're explaining which permissions are needed _and why_.
206- In the contributing section, I don't think you need to explain _how_ to make a
207 pull request. I'd link to GitHub's documentation instead. Instead, this would
208 be a good place to put some basic guidance about coding style, passing lints,
209 dependencies, etc.
210- The ideas for contributions is a great touch. You could open issues for these
211 and link to them in the readme, so people can easily see what's being worked
212 on and what isn't.
213- In keeping with your goal of making it accessible to contribute, in the
214 troubleshooting section, it may be a good idea to direct people to open an
215 issue if their problem isn't listed there.
216
217## conclusion
218
219I hope some of this was helpful. Your project is cool, and you seem very
220earnest, so I'm interested to see where this goes. Welcome to the community :)