This is a response to a
[reddit thread](https://old.reddit.com/r/opensource/comments/1mfr21t/experienced_developer_trying_open_source_for_the/).

- Author: Daniel (ficd).
- This document is dedicated to the public domain.

## preface

I'll just preface by saying that my policy is honesty --- if anything comes off
as rude, that's not my intention. I'm always happy to see people actually asking
questions and engaging. All too often, there's folks that come barging in with
vibe--coded slop that doesn't solve any real problem, then act entitled to our
(FOSS community) attention and feedback. You don't seem to be doing the latter,
which makes me feel comfortable writing a thoughtful response knowing it won't
be totally ignored; I have no expectation that you will agree with any of what I
say (I am quite opinionated), but I have a feeling you'll at least read and
consider it :)

## not all about building community

With that being said, I want to point out that being part of a community and
contributing to a project is a different thing from developing your own project.
In the latter case, I think you may be putting the cart in front of the horse.

What I mean by this is that you seem to be pretty focused on building a
community right off the bat. There's nothing wrong with that, but in my opinion
it's the wrong priority. Pretty often there's posts around here asking about how
to gain visibility, how to build a community, devs feeling demotivated because
no one's using their project. It's the natural consequence of applying a
"corporate" or "side--project hustle culture" type of mindset to open source ---
but I feel like it fundamentally misunderstands what we're all doing here.

There aren't many people going around hunting for "projects to contribute to".
People will naturally contribute to projects that they _use_ and that they
_believe in_. Personally, when I come upon a brand--new project with barely any
participation besides the maintainer, but the README or documentation website is
chock--full of "how to contribute", "community guidelines", etc., it feels a tad
disingenuous --- like the goal of building a community outweighs the goal of
building good software. Not to imply that's always the case; but that's just the
impression that I (and I imagine other developers) tend to get.

I seriously don't think it's actually about having users or contributors. Let me
offer some personal examples. I maintain many projects. Only one of them has
users _that I know of for sure_. The others _might_ have users, but I don't
actually know. I receive the occasional PR, issue, or email, which I address
earnestly and move on.

And yet, I don't feel any less "part of the community". You're still an
open--source maintainer even if no one contributes. My biggest project so far, a
custom SSG called [Zona](https://git.ficd.sh/ficd/zona), is on a self--hosted
Git forge with closed registration, meaning I only accept contributions via
`git send-mail` (in theory, since no one has tried yet). But I don't consider it
to be any less worthy of a project, or myself to be any less of a maintainer
just because of it. I _also_ don't think a project needs a super comprehensive
community code of conduct, issue & PR templates, etc. to be accessible for
contribution.

## documentation matters a lot

The _most_ important thing, **by far**, is good, _detailed_ documentation. You
don't need "how to contribute" docs if you can explain well how every component
of your project works, and _why_ it works that way. That's the kind of
documentation that can equally benefit both users and potential contributors. In
fact, most contributors start out as users -- and no one will end up
contributing to a project they can't figure out how to use in the first place.

Now, all of that said, considering your corporate background and your stated
intent to "stop being a spectator", I think you're doing _very_ well. It can
often feel like FOSS is being inundated with disingenuous people that just want
to pad their resumes, and your project doesn't come off like that. Let me share
_why_, as someone that's seen a _lot_ of garbage: the project addresses and
solves a _real_ problem, one that feels personal and relatable. It doesn't seem
like one of those "I built a FREE and OPEN SOURCE tool that does XYZ" (the tool
in question is just a wrapper around ChatGPT API). This alone already gives you
more credibility than half the people I see posting about their new projects.

## answers

Here's how I'd answer your questions:

- How do you write issues that actually help newcomers contribute?
  - Explain _precisely_ what the problem is, how it should be solved, and
    perhaps include a starting point, like "the `module_name.foobar()` is the
    likely culprit".
- What's the etiquette around reviewing PRs from strangers?
  - Be polite, but remember that this is your project, and you're under no
    obligation to accept code that either 1. sucks ass, or 2. takes the project
    in a direction you don't agree with.
- How much roadmap should you have vs letting community drive direction?/How do
  you balance your vision with community input?
  - I genuinely believe that the best projects are led by opinionated developers
    with a clear vision. I also don't think you need to worry about this until
    you actually build a sizable community. Until then, this is _your_ project
    with the occasional contributor.

- What are the unwritten rules newcomers to open source should know?
  - Do **not** act entitled. Maintainers are not required to review your PR or
    Issue, _especially_ if it's low effort. Your project is not entitled to
    feedback, review, users, or contributors. **Make people _want_ to do it
    anyways.**
  - Maintainers and other contributors are people too -- besides the obvious
    "respect" point, this means that **they're capable of stupidity as much as
    anyone else**. If a contributor is an asshole when reviewing your PR,
    _ignore them_. If a maintainer dismisses _valid_ concerns with an attitude
    and without justification, _don't bother_. If it's that important, fork the
    project. This is why `basedpyright` exists.
  - It's OK to fork. Don't feel pressured to _always_ contribute upstream and
    water down your changes as a result. If your change is _really_ that
    important, and it's not being accepted (sometimes for perfectly valid
    reasons!) then it's OK to fork!
  - Licenses matter, and should be chosen intentionally. Don't just slap MIT on
    everything, really consider "what license makes sense for what I'm
    building?"
  - People that are here _just for the sake of being here_ (resume padding,
    clout, validation, whatever) will not be taken seriously. Of course, people
    that are _learning_ or pivoting into FOSS are very welcome; the key is
    transparency and sincerity, not pretense.
  - There's nothing wrong with building something open source that _integrates_
    with something proprietary; just be upfront about it. If your tool heavily
    relies on, say, proprietary APIs or has a proprietary dependency, and that's
    not stated upfront, people will feel tricked.
- How do you evaluate if a small project is worth other people's time?
  - Is it worth _your_ time? If someone completely different were writing this
    project, would _you_ care?
- Any red flags that scream "this person doesn't understand open source
  culture"?
  - Way too much emphasis is put on it being "FREE and OPEN SOURCE" in the
    readme, the Reddit posts sharing it, etc.
    - This _always_ feels like people that couldn't care less about the FOSS
      community are cashing in for portfolio points. It just feels so _icky_. If
      you're posting in r/opensource, then _obviously_ your shit is
      open--source. There's also this underlying assumption that just _because_
      the project is open source, it's somehow entitled to our attention,
      feedback, etc.
  - Learning projects that **advertise themselves as something they're not**.
    - There's absolutely nothing with creating something impractical or
      reinventing the wheel for your own learning or fun. But _please_ don't kid
      yourself and say some shit like "the new CLI native todo app developers
      have been waiting for!!!"
  - README is infested with emojis (like, one emoji per bullet point). Sure,
    this isn't always a reliable heuristic or indicative of low--effort, but
    first impressions matter a lot, so it's better to err on the side of caution
    here.
  - If documentation is obviously AI--generated. There's no clear heuristic for
    this, but... from what I've seen, if it walks like a duck...
  - The "documentation website" is way too fancy, and sometimes more polished
    than the project itself
  - There's a "buy me a coffee" button on a project that clearly took minimal
    effort to create
  - The documentation makes assumptions about your OS:
    - When a project bills itself as being "cross--platform", but the readme
      only has installation instructions for Windows, immediate red flag --- now
      I know this likely hasn't been tested on any other platform.
    - Linux instructions assume Ubuntu/Debian and are not generic
  - Junk is checked into the repo (may seem obvious, but I saw a "FREE and OPEN
    SOURCE" project with `__pycache__` checked in the other day)
    - (I'm likely to give the above more grace than when I see a `.cursor` or
      equivalent checked in -- if you couldn't be bothered to code it yourself,
      why on _**Earth**_ should I consider using it? Giving "feedback" on a
      project you didn't build?)

The above list isn't comprehensive by any means, and I'm sure folks will have
disagreements as well.

## readme feedback

In terms of specific feedback on your README:

- In the prelude section, I'd separate _what_ the extension does, and _why_ into
  separate sentences or paragraphs. For example, "TuringOff (...) blocks AI
  chatbot websites by doing X, Y, and Z. Our goal is to encourage (...)"
- Describing the blocking message as "humorous" in the documentation itself
  feels a bit conceited. You can't really make an assumption that people will
  find it funny; and frankly, the block page being "funny" doesn't constitute a
  feature. The fact that there _is_ a blocking page is worth mentioning, but I'd
  word it differently.
- I could do without the emojis on each heading, but at least you've kept them
  tasteful. Be wary of emoji overuse though, it can smell of AI.
- I recommend explaining the features in more detail in a separate section. For
  example, it's not immediately clear what makes the AI detection "smart". An
  explanation would go a long way in making your project more credible. Re:
  lightweight; this means different things to different people. Some benchmarks
  would be great to back that claim, and demonstrate that you've put in the
  effort.
- Installation instructions are great. Nitpick, but I'd change quotes like "Add
  to Chrome" to inline code: `Add to Chrome`.
- Usage instructions are good. Since the means of interaction is GUI, I think it
  could benefit from some screenshots.
- I'd get rid of the technical architecture section in the README. The "Key
  Features" listed there don't seem like implementation details, they're
  important selling points, so I think it's worth merging them with the features
  listed at the top of page. For the components, I'd recommend creating a
  separate `ARCHITECTURE.md`, moving them there, and then fleshing out that
  document a lot more.
- Perhaps pedantic, but I'd rename Customization to Configuration, since this
  affects the actual core behavior of the extension.
- Also, maybe I'm misunderstanding the extension, but wouldn't you need to
  install the extension manually, or do some tinkering within your browser
  profile to modify `background.js` and `messages.json`? If that's the case, I'd
  make a note about that in the section because it's not immediately clear. For
  example, can this be done on the fly, or does the tool need to be rebuilt
  after changing one of those files?
- Same applies to styling. Also, since this section is so short, I'd merge it
  into the above.
- I love that you're explaining which permissions are needed _and why_.
- In the contributing section, I don't think you need to explain _how_ to make a
  pull request. I'd link to GitHub's documentation instead. Instead, this would
  be a good place to put some basic guidance about coding style, passing lints,
  dependencies, etc.
- The ideas for contributions is a great touch. You could open issues for these
  and link to them in the readme, so people can easily see what's being worked
  on and what isn't.
- In keeping with your goal of making it accessible to contribute, in the
  troubleshooting section, it may be a good idea to direct people to open an
  issue if their problem isn't listed there.

## conclusion

I hope some of this was helpful. Your project is cool, and you seem very
earnest, so I'm interested to see where this goes. Welcome to the community :)