HN Reader

I liked the humble, “lessons learned” tone of the post.

> every feature you add is a feature you maintain forever.

This.

Keeping a framework/app/SDK “pure” is very important, in my experience.

The first point about documentation really has to do with the question: whom are you willing to support?

Instead of seeing it as "users of X platform", I think it's more useful to divide user groups into:

1. Completely non-technical users who, at worst, wouldn't know how to download anything, and at best only know how to install from an ".exe" file;

2. Middle-ground users who, at worst, are not willing to learn your preferred way of installation, or at best, are new to non-common installation methods;

3. Technically proficient users who, at worst, have arbitrary reasons for disliking your preferred way of installation, or at best, have legitimate reasons for disliking it;

4. Your ideal technically proficient users.

FOSS is often geared towards the fourth category, and for good reason. But if you want your tool to be adopted more widely, you have to learn more about those other user groups, and how to support them beyond documentation.

And here I'd say it's also fair to look for good reasons or funding for that extra support, because if it's not rewarding work, it doesn't have to stay free as in free beer (even if it's FOSS).

I don’t understand. It’s your project, you do what you want and nothing more.

Kinda frustratingly written by ai

As an Apache PMC member, I often ask myself: Can I maintain focus and dedication to open-source projects for an extended period? My answer is: extremely difficult.

Once the initial enthusiasm fades, it becomes difficult to maintain the project.

>but here's the thing: people come from different backgrounds. what's obvious to me after building the thing isn't obvious to someone installing it for the first time.

Sure, but you're also not obligated to do... well, anything. And people are also allowed to read documentation and code and put in the effort to build and install things themselves. What happened to the oldschool hacker spirit that rewarded learning and helping yourself? If you show up to a group of people and say "how do I make this work?" while showing zero evidence that you've actually done anything, you'll be politely told to fuck off. I promise it's okay to say no to people, especially people who haven't demonstrated that they've put in their own time to understand something.

But this is immaterial anyway. I don't know how to better explain that you don't owe your time to strangers on the internet, some portion of whom are probably not even human. Alternatively, you could get them to pay you, especially the organizations "behind corporate proxies". If they can afford a corporate proxy, they can certainly afford your time, as long as you value it appropriately.

So yeah. Stop working for free, and stop treating every last internet stranger as relevant.

This is actually nice and balanced, but the title is misleading. I feel like ALL I hear about maintaining an open source project is how hard it is and how people burn our. I almost never read a blogpost or comment declaring how rewarding it is. So, this was a nice (slightly) more balanced view.

> maintaining kaneo means helping people debug their setups. and honestly? it's taught me more than i expected.

> people run kaneo on setups i never imagined:

> behind corporate proxies

> ...

> in kubernetes with custom networking

It's OP's project so they're welcome to support whoever they want but I definitely would not offer free support to customers who are obviously using the product commercially, especially in large enterprises.

It's FOSS, so they can use it for free if they want, but if they need custom support or features, they're a great user to tell, "Sure, I'm happy to help you with that if you purchase a $500/yr support contract." You'd be surprised how many customers like that don't care because they have a corporate card and that amount is too little to require approvals or much process.

For anyone interested in this (and certainly for OP) I highly highly recommend the book Working in Public: The Making and Maintenance of Open Source Software by Nadia Eghbal. When I was raising my profile on my open source farming robot, this book really helped me understand the types of projects one might want to foster, how to think about users, and generally gave me very helpful guidance on becoming an open source maintainer!

Take a look: https://press.stripe.com/working-in-public

This is why I like building outside plant. You put the fibre up on poles or pull through ducts, splice it, bring it into the building, hook it up to the equipment, make sure it's working and.... you're done. It works until something breaks, usually for a very clear reason (power outage, drunk driver, rodent, vine, lawnmower man, fibre seeking backhoe, dump truck, direct lightning strike, thermal cycling of a marginal splice, failure to seal a gasket properly resulting in water intrusion that stresses fibres when the water turns into ice, ...), but those become quite rare if you're done your job properly.

On the other hand, software is never done. Even simple features, like headphones, regress these days. (I missed a meeting today because my phone decided to send audio notifications into the black void of the heat death of the universe because I didn't unlock my phone after plugging the headphones into the USB-C port of my iPhone -- the audio didn't come out of the speaker, nor out of the bluetooth of the car I was driving. No sound worked until after the phone was unlocked.)

At least with open source software I can fix the bugs I care about, but the fun goes away once you have to deal with other people to get things merged.

Is there a community of software Luddites I can go live with where we build simple technology that works and works well?

It's interesting to see that the "the diversity of environments" section only talks about work for supporting different installation / deployment methods.

Back in the day, with different technologies, most of it would have been "strange compilers and environments" that had to be supported.

> someone opens an issue: "how do i install this?"

Honestly, this is a GitHub thing. You wouldn't get that issue on sourcehut, bitbucket or self hosted.

GitHub is the lowest common denominator for users.

You need to stop wanting to help others as a developer, in that context it's a toxic mindest that will slowly kill your projects, time, personality, passion, and self. You made the project for you and chose to share it to others, that's all you need to feel responsible for. If others need to adapt it to fit their use cases, it's on them to do so.

These are good takeaways from someone who seems to actually care about the users of their project, which is refreshing to see. I've gotten into discussions on this forum with people who think and do otherwise. (Case in point[1].)

> they're not demanding. they're engaged. that's a gift.

100%!

Open source maintenance is a difficult and sometimes thankless job. It requires a lot of communication, careful balancing of the project's vision and user requests; tolerance, patience, honesty, transparency, gratitude, humility, but also confidence, sternness, and above all else, dedication to improve the project for everyone, not just a select few. It seems that the author gets quite a few of these right.

A few notes from my own experience:

- Documentation is important, and they're right that it is never "done". That said, you also have to assume that it's written for a specific audience. If a baseline level of technical proficiency is needed for your project, then you shouldn't need to explain topics that bring people up to that level. Sometimes it's a better use of your time to address the occasional support question, than to add documentation that would be irrelevant for the majority of your users. Besides, if those support questions are visible to the community (e.g. they're on a discussion forum), then your answers there can serve as unofficial documentation for people who need it.

- Speaking of which, a discussion forum is crucial when building a community around an open source project, or any project, for that matter. It is another source of information for users, you can use it for announcements, etc. And once you have power users and people passionate about your project, the community itself can help out with support duties. Definitely make this as accessible as possible, make it public, and don't use a closed platform like Discord. A real-time chat platform could be useful, but an async searchable old-school forum is much better for discussion and support.

- Code contributions are a double-edged sword. On one side, it's incredible that some users are passionate about the project enough to invest their time and effort in improving it, and are willing to share their improvements with everyone else. But on the other, when their code is merged into the mainline project, it becomes an additional maintenance burden for core maintainers. Those contributors will hopefully be acknowledged for their work and everyone will appreciate it, but if there are issues with that part of the code, it will be the original maintainers' job to fix it and improve it, not the contributors'. The article mentions this already, but this is another reason to be extra vigilant and judicious about which code to accept, and which not. Most contributors will understand.

Kudos to the author, and best of luck with the project! It's certainly on my radar now.

BTW, looking at Kaneo's web site now, the "free forever" next to the Cloud link is not a good sign. Maintaining infrastructure is a financial burden. Nothing should be "free", and definitely not "forever". Please: add a commercial tier where people can pay you for the resources they consume. This is orthogonal to open source, and you should be compensated, not just for the infrastructure you maintain, but for your work. Everyone will understand this, as long as you keep it fair. In fact, it serves as assurance for any potential users that the project is in a healthy state, and that it will likely continue to be maintained.

I'd be happy to discuss this further and offer any guidance if I can. My contact info is in my profile.

[1]: https://news.ycombinator.com/item?id=46051393#46052504

I get that he just wants to build something alone in his basement -- without product managers, sales guys, or customers with SLAs breathing down his neck. But he's doing an enormous amount of work specifically to avoid charging money for something that's already providing real value. That's the part that feels odd to me.

If you've got "200 users" who rely on your tool so deeply that a migration glitch would seriously hurt their business, you're past the point where this is a casual side project. That's the point where you should at least have some path for people to pay you.

In my head there are three phases of an open-source project:

* Toy – "I scratched my own itch and threw it on GitHub."

* Product – "People actually rely on this. Now I owe them migrations, docs, and not breaking stuff."

* Infrastructure – "If this dies, someone's company explodes and I'm on the front page of Hacker News for the wrong reason."

This post is basically the story of moving from (1) to (2).

What I rarely see is a maintainer explicitly saying which phase they're in. Users see "kanban board, nice site, good docs" and instantly a user is going to map this to, "Jira replacement!" And the author is thrilled to be compared to a polished SaaS!

But then both will be "shocked" to realize that one person can't match an entire product team, support team, design team, etc.

I think there's a lack of honesty in a lot of open source projects. I'd love to see more READMEs say things like:

* "Hobby project. I reserve the right to disappear for a month."

* "No guarantees, no SLAs. Use at your own risk!" (or even more blunt, "If you use this in production, or for mission-critical business practices, you're a fucking moron.")

* "If you're a company depending on this, you should be sponsoring it."

Anyway, seen this countless times... And the real tension starts when the author's excitement about having users surpasses the amount of work generated by those users. As long as the author wants to avoid working on a team, with business rules, and other stakeholders... it'll never actually scale.

Worse, the difference between users and customers is that there's no barrier to entry. Users expectations drift upward -- whether they are paying or not. Users don't just want fixes -- they want roadmaps, guarantees, backwards compatibility, and custom migration help. The code is open-source, but the longer the project goes on, the more the expectations drift towards enterprise-grade.

Boundaries matter. "No, that's out of scope." "No, I won't support your forked schema." "No, I can't chase down your custom patches." Those aren't signs of being unhelpful -- they're what keep the project from collapsing under its own weight. And when you have to start saying things like this, you've past the point of needing a bigger team... which means you're also past the point of where you should have started charging money for your product.

Yeah running a miniture incarnation of data centre Jira (i.e. the old one where people self install and uograde) as a single dev. That will be a lot of work!

I like the article a lot. Very thoughtful.

I mean, Docker Compose could use to be more robust. I recommend Caddy for things like this.

Don't help people who won't help themselves.