As the dictator author/maintainer of a tiny library¹ (45 functions total), I can confirm the manual wouldn't be half as good without external contributions. And I daresay this manual is a major contributor to the usability of the whole project.
As a new user of libcurl, I was recently able to quickly implement FTP upload and adapt it to our specific use case thanks to their tutorials and API documentation. I was even made aware of the lack of thread safety in old versions thanks to that same documentation, so I could warn my team that we should update.
Documentation is bloody important. Almost as important as the code and the test suite themselves.
IMO a big portion of what a good test suite should be is documentation. Tests are examples of things that do and don't work, with some explanation of why. Examples in documentation can (for some doc frameworks & languages) be set up to run as tests, ensuring they stay current and actually work. Tests are machine-readable documentation.
This is something I _really_ like about D.
Unit-tests are built into the language, as is comment-based documentation—put those two together and you get unit-tests as documentation examples built into the language; all it takes is to put a documentation comment (which can be blank) right before a `unittest` block after a declaration.
I took the same "docs are tests and tests are docs" approach with integration testing when I created this library: https://github.com/hitchdev/hitchstory
I realized at some point that a test and a how-to guide can and probably should actually be the same thing - not just for doctests (https://docs.python.org/3/library/doctest.html), but for every kind of test.
It's not only 2x quicker to combine writing a test with writing docs, the test part and the docs part reinforce the quality of each other:
* Tests are more easily understandable when you attach written context - the kind that is used when generating a readable how-to guide.
* How to docs are better if they come attached to a guarantee that they're tested, not out of date and not missing crucial details.
* Integration test driven development where how-to docs are created as a side effect is really nice.
Yep, also D and Rust have similar things, and likely other languages. I didn't feel it particularly useful to try to list them all, just to point out that tests & docs are two aspects of the same thing.
Oh yes, and for languages where that is not directly possible, there are still ways - I implemented libraries for Chicken Scheme in org-mode with org-babel; the examples are simultaneously tests, runnable directly from within the org file, and live next to the code together with the docs. org-babel's tangle and org's export take care of the rest.
> Examples in documentation can (for some doc frameworks & languages) be set up to run as tests, ensuring they stay current and actually work.
As an example, in Elm (as in many languages) your publicly exposed functions in a package (a.k.a. library) are required to have documentation comments. This often includes a simple example because, well, it's easy to grasp. The build tool elm-verify-examples runs all of these examples and verifies that the output is what you say it is. It pretty cleverly uses the inline comment delimiter as the start of an arrow so that the rendered code listing in the example is still syntactically correct.
That depends on what we're testing, and how thoroughly. Tests as documentation are amazing when the specs are in flux and we'd rather document stuff in one place instead of duplicating it between tests and user manual. But when the specs are fixed this is much less of a problem.
Then there's how much you need to test. Good tests go way beyond readable examples, they usually involve generating tons of tests with more or less random data and running them in a loop (property based tests). I do this, and to be honest I wouldn't recommend end users read them.
Agreed, that's why I said it's a "big portion" and not "all" of what a test suite should be. Many tests are "how-to guides" in the Diátaxis documentation approach[1]. They're also useful as a part of tutorials. Anything over 25% is a pretty big portion of the total documentation.
Automated property-based tests, fuzz tester cases, and similar things aren't documentation at all.
I subscribe this to a certain degree but there are limits. Some tests are just too complex to be used as documentation. Sample code is better in such cases.
Then you're (unfortunately) not quite the target audience. Broadly speaking my library lets you secure communications and authenticate stuff. It does not however provides a turnkey solution for most of that. It has signatures, but no certificates. It has key exchange, but no protocol handshake. Thus as it is, it requires some familiarity with cryptography.
At your (apparent) level of understanding, you're probably better off reaching for a higher-level alternative, possibly even full applications like Age (that let you encrypts files), or Signify (that let you sign files).
Yep, and if you don't know what a crypto library is, the Features list does a very good job enumerating all the things the library lets you do. I have no idea what the GP is talking about.
A description of the file system structure of the repository. Explains how things are organized, where existing stuff is located and where to add new stuff.
I run tree on the repository root, append the output to the README and add comments to every line explaining every directory and sometimes every file.
They are crucial for open source - documentation, assets, etc.
But they can also mess up a project with giving power to non-developers who focus on changes like redoing the UX every release, to the detriment of stability, functionality, adoption, and so on. They also attract busybodies concerned with "politics", more so than coding does. It's also a great domain for bikeshedding (as anybody feels like they can do it).
You've clearly touched a nerve, but this article barely talks about UX or political issues at all, it's overwhelmingly about low-recognition work like improving docs, filing good bug reports, and being active in the project's support channels.
The people who do the things that the article talks about do not tend to be busybodies because these are tasks that don't get a lot of attention or recognition, which is why this article was written.
Yes, the usual attack vector for entryists in an open source project is usually through non code contributions. Intensely political people figure this out pretty easily.
But, what can we do? I like to believe that those anti-social elements are (very vocal) but a small portion of the universe of non code contributors. Project leaders just need to be a little less naive and keep an eye on this possibility to tackle the problem as soon as it appears.
Is it even really true, though? This feels like the kind of idea that circulates among techies who feel like "their people" wouldn't engage in that kind of politicking, even though it's been obvious everywhere I've looked that we're just as capable of making a mess of an organization as anyone else.
I don't know. You could be right. I've found my share of intensively conniving and political techies too. Even some that were highly competent/skilled but had this passion for politics, and a tribal instinct of building a clique of a bunch of followers steamrolling over everyone else wherever they went.
But on the other side, the non-tech infiltration route is also real.
Yes, but the perception seems to be that those people are non-technical people who felt empowered to become involved because the project encouraged non-code contributions like documentation, bug reports, and helping out in the support forum.
The reality as far as I've seen is that the people injecting politics into the discussion are developers, not "normies". The perception exists because some of us have a stereotype of a developer as someone who's only interested in the technical details of a project, so the people who bring unrelated concerns to the table must be non-technical.
When people say things like this, the first thing I think of is ncurses' absolutely legendary licensing and social drama[1]. Be warned: reading that page in full will take you at least an hour.
To find petty bickering, look no further than most technical contributors. Accusing non-technical people of this sort of thing isn't borne out.
It's just as true today, though. When the Rust mod team resigned en masse in 2021, it was announced by a programmer (the author of ripgrep) [0], and the conflict was with the core team (also programmers). A supermajority of the contributors to open source projects are programmers, so most famous meltdowns are going to be conflicts between programmers, not between programmers and the tiny minority of non-technical contributors.
I'm still waiting for anyone to give an example of an open source project meltdown that was triggered by non-technical contributors.
Do you think people are looking to attack and want a vector? A much simpler, less paranoid explanation is that they get involved and then perceive problems. Some of those problems might even be real!
> But they can also mess up a project with giving power to non-developers who focus on changes like redoing the UX every release
Have you found that a new developer is meaningfully less likely to recommend redoing the UX compared to a new non-developer? Personally my sense is that desire to update the UX is more closely correlated with the "newness" than development ability.
>Have you found that a new developer is meaningfully less likely to recommend redoing the UX compared to a new non-developer?
Kind of. New developers tend to do some bug fixing here and there, or implementing some small feature, not dictate major changes. And if they do, they're ignored or debated, and that's it.
That would be overwhelmingly true of most non-developer contributors too: they maybe submit one feature request that gets brushed off and then aren't heard from again. The question isn't whether most members of a given demographic are successful in derailing things or not, the question is if non-developer contributors are disproportionately likely to be disruptive to the project.
I don't believe that to be the case, but am open to examples that provide evidence in favor of the claim.
That is an interesting one. "The internet doesn't forget", they say, but all the bs and mudslinging around that got basically purged from the internet. It's impressive sometimes.
Every time I see a respectable project use a Code of Conduct I remind myself that, unfortunately, Caroline Ada won[1] and also that github will ban you if your code uses words they don't like[2]
Eh. Some things can still change going forward while others won't. The future is unwritten.
I see cultural change as analogous to steering a large ship. You won't be doing any sharp turns but you can gradually move it in a different direction.
I, for one, don't believe in the freedom that "free enterprise" supposedly affords in theory.
I believe in the practical reality, in which some companies/social media/products become near monopolies, and there's always an additional cost to "not using it", not just "chose this or that and get equivalent functionality".
In general, I find your answer not that different than the right wing "if you don't like it here, just move to another country".
> "if you don't like it here, just move to another country".
But that _should_ be easier in the digital world than the physical one. That Github has become such a center of everything _is itself a problem_.
Codeberg is one answer to that: they host open source projects and also provide CI to those projects on an as-needed basis (decoupling the service from financial constraints by limiting their audience and therefore their costs to provide this service). Hosting code forges for particular communities is another way (I think SDF does this for theirs?). It's easier today than it ever has been in the past.
If we just say "I have to use the monopoly because it's too expensive not to" than we're part of the problem.
I'm not a fan of private corporate control of communication in any form, but the complaints of people who get kicked off services for behaviour that would have them physically removed from private premises are always amusing to see. You join the service, you agree to the terms and conditions, you breach said T&Cs, you complain about "mah free speech!"
If you actually care about free speech, and you have the technical ability to help with either creating, documenting or promoting federated, open source, distributed communication systems, then do so.
I'm jaded on this because I've been involved in a couple of projects with the stated end goal of true freedom of speech only to be torpedoed by either selfish greed or legal ramifications.
I believe the solution to this (and the reason we don't have it) is no longer technical, it's societal.
None of them are monopolies. The EU will eventually be 'looking at' corner stores. If it becomes too costly to operate in the EU, multinationals will eventually leave.
Maybe someone in Europe will invent another cloudflare, github etc. They do have Telegram to replace WhatsApp.
They are monopolistic. If I want to buy Coke, I can go to nearly any store. I don't need to only go to one store.
If I want to interact with an open source project on Github, then I have to go to Github. I can't choose to go to sourcehut or bitbucket to interact with that project.
If github was just another git server (aka just another store) and I could go to any store to get coke (aka open source project), then it wouldn't matter. But it's not just another store or interface.
The combination of git being an open protocol, and open source licensing (as it's meant to be) means that you can definitely fork and re-host many projects on Github. The issues that practically stop you from doing this aren't actually the fault of Github. I'm not trying to defend Github here, but it's not the best example you could have chosen.
What open source project uses multiple DVCS repositories (e.g. bitbucket, github, sourceforge, sourcehut, etc) for one project in sync with each other? I haven't found a single one that does that.
And that's before we start talking about tickets and discussions, pull requests, wiki and documentation, etc.
> What open source project uses multiple DVCS repositories (e.g. bitbucket, github, sourceforge, sourcehut, etc) for one project in sync with each other? I haven't found a single one that does that.
There are some that have official mirrors on GitHub and perhaps even accept pull request here. But I think that only reinfoces the notion that GitHub is an effective monopoly.
The product github supplies is a 'service', project hosting. There are multiple providers of that service. Github is not a supplier of the software projects themselves any more than the telco is a provider of conversation or S3 is a supplier of Netflix movies.
censorship is still censorship just because a private corporation does it.... and it's not a free market at all, there are many regulations concerning these industries
How could non-developers force changes to the UX? That requires changes to the code, no?
As for politics and bikeshedding, I have seen plenty of that amongst developers so I'm not convinced non-developers would be more likely to engage in it.
With the amount of hate I see over Gnome's interface designs, if it was true that submitting mockups was enough to force a project to change its direction, Gnome would have a different interface.
The fact that Gnome was able to choose a direction they wanted to go and then go in that direction even over the extremely vocal protests of a large portion of the community is if anything proof that you absolutely can reject mockups from community members if you don't want to implement them. Ultimately, the project decides what interface it wants to have. And community members can protest that direction, they can complain that project's priorities are wrong, they can fork things (and Gnome has forks), they can do whatever -- but they lack the ability to force the project to abandon a design that its owners like. That's a good thing about Open Source.
The idea that UI designers are somehow hijacking Gnome because they advocated for designs that the org voluntarily implemented... it makes no sense to me at all. Does the org own the project or not, it's their choice. Unless the idea here is that Gnome should have been obligated to accept design critiques from people outside of the project and change their internal designs just because the people proposing changes from outside the project knew a programming language; but that would be a silly thing to say.
>The idea that UI designers are somehow hijacking Gnome because they advocated for designs that the org voluntarily implemented... it makes no sense to me at all. Does the org own the project or not, it's their choice. (...) Unless the idea here is that Gnome should have been obligated to accept design critiques from people outside of the project and change their internal designs just because the people proposing changes from outside the project knew a programming language; but that would be a silly thing to say.
Well, here's the problem: these people proposing the changes are not outside the project. They are within the project. And their vote is as good as a dev's (and it's easier to gather dozens of them, as it doesn't require skills for doing the much harder and more prolonged dev work).
And in orgs with a non-dev bureucracy and management (like Mozilla and Gnome) they can get buy-in from those "higher ups" too. And they can also create enough friction and bikeshedding on regular FOSS projects too, as long as those don't have a BDFL and everybody has a voice.
> Well, here's the problem: these people proposing the changes are not outside the project. They are within the project.
So what, your issue is that project owners get to decide who they work with? If the people working on UI in Gnome are part of the Gnome project that is not in any way randos coming in and bikeshedding over the UI -- it's a project self-determining what it wants to do. I'm sorry they're organized in a way that you (an outsider to the project) find offensive.
Yeah, of course the vote of project members is as good if not better than the votes of people outside of the project because these projects get to set up their own orgs and governance structures and they don't have to justify or prove to anyone outside the project why the people they work with deserve to be there. And that is one of the things that is amazing about Open Source. You can just go do stuff and when somebody else shows up on your Github repo and says, "the UI designers are ruining your software" you can tell them to take a hike because they don't get to decide how your project is run. They're not required to consult with you.
----
I don't see what any of this has to do with no-code contributions. Encouraging non-coders to write documentation and tutorials and help with feature suggestions is bad because you have a problem with project management?
By the "higher ups" I guess you mean the literal orgs behind the projects? You don't need quotation marks for that, those are just called higher-ups, that's how organizations work. It's still the case that the people who build and control Open Source projects can take them in any direction they want regardless of what people outside of the projects want them to do.
Of course, Open Source has lots of mechanisms to avoid problems with bad project direction -- notably, forking, which should be hecking easy since all of the people complaining are apparently such excellent programmers.
I present to you Ayo.js, a long-dead Node.js fork with almost as many moderators as "core" members. I'm sure there are a variety of reasons why it bit the dust but I'll always view it as a lesson in priorities.
In an ideal world, developers write documentation as they're developing. This seems to work really well for OpenBSD and its various project, all of which have some of the best man pages out there.
IMO it works a lot better for software that is aimed at other developers. Writing documentation that is accessible to non-technical users is a different skill.
All BSDs really, and I also want to mention GNU projects, they enforce this well, too. I made contributions to org-mode, and they made it clear that they won't accept a line of code without accompanying tests and, if applicable, handbook adjustments.
lots of people "feel like they can" code, but surely projects are capable of weeding out bad code contributions. why should it be different with non-code contributions?
Care to expand? What bad contributions did Darktable accept? Why should one not use Darktable?
Also since you seem to be familiar with both project, is Ansel compatible with Darktable sidecar files? If an existing Darktable user were to move to Ansel what can they expect to carry over and what might be lost?
Then to endure the endless irrelevant debate, citing the code of conduct, as to why they have to accept the PR? (As illustrated in a few of these posted github tickets).
Bikeshedding has become a thought-terminating cliche.[1] 99% of bikeshedding () I see is about things that absolutely have to do with how working at a nuclear power plant is like, not merely how you feel when you commute to and fro. Syntax? Absolutely something that matters. How an API is structured? That too.
It just so happens that everyone can have an opinion on it. So you have a problem with a thousand possible voices, and that many of them might be drive-through busibodies. But that’s still not bikeshedding.
True bikeshedding would be haggling over the styling of the Who Are We page of your promotional website.
[1] Like many, many nouns based on programming blogs from the last twenty years.
> Flowers recommends building a community on a chat platform like Discord, Gitter, or Slack to make it easier for people to get involved informally with a project. “It makes people feel less hesitant to ask quick questions,” she said. “A lot of people are intimidated to ask questions on repositories.”
I have asked questions on repositories, more times than I have fingers. I have created pull requests that fix problems I've had, fewer times than I have fingers. I can think of twice those have yielded positive results: one time I received a clear answer to a question which solved my problem; another time a pull request was rejected with an explanation. (It was a fair enough reason: my change would have broken a different use-case I hadn't considered. I used my code fix locally - on a personal project - until I stopped needing that project.)
Far, far, far more often than that I have seen my questions already asked, or pull requests already created, with no answer or merge forthcoming. I'm not intimidated by the process, but have come to think of it (on GitHub, at least) as fairly pointless, and it's been ages since I've bothered. (I've also come to avoid using GitHub projects with a single developer, and /or without a really active and recent update history.)
I understand why "I've made the code public; I don't owe anyone anything else; fork it if you don't like it" is a prevailing attitude amongst GitHub project creators. I also think it obviates the original premise of GitHub - to create collaborative communities of developers and users - to the platform's detriment. It's not surprising (but still disappointing) that people are looking to other platforms for the community-development (in both senses) that GitHub could, and was intended to, support.
GitHub has probably been more successful than any platform at connecting developers, but I think it is ultimately subject to the same limitation as the big social media platforms in that regard: if you are connected with everyone, you aren't really connected with anyone. When someone creates an issue or pull request on your repo, you have no idea about their competence or their intentions. You have no idea if they are trying to sneak in malicious code, or if they are trolling you, or are going to get offended if you suggest changes to their PR, or if they will have the capacity to understand your detailed technical response to their query. In a word, there is no trust. So if it's a side project (maybe one of many) it's often easier to just ignore contributions and treat GitHub as a way to publicly host your code on a "take it or leave it" basis.
For true collaboration, maybe other, smaller forges where developers are more likely to have something in common would be more useful.
> Flowers recommends building a community on a chat platform like Discord, Gitter, or Slack to make it easier for people to get involved informally with a project.
Sample size n = 1, but I saw a lot more engagement on my projects when I was hosting mattermost helpdesks for people to join and ask their questions. Unfortunately I had to shut them down because turns out having random individuals ping you on your phone about an issue that is well documented gets very draining.
Honestly, public forums, stackexchange, etc also have a huge benefit over something like discord/gitter/slack, in that previously asked questions are indexed by Google -- which is often the first recourse of someone trying to figure something out. If the discussion is sequestered behind an authentication gate, it can't help other folks out down the road.
As someone who has been active with the WordPress community for about fifteen years now, the early documentation and Codex's robust documentation and easy on-ramp for new developers always struck me as one of the main reasons for WordPress's growth over the years. In the early days of the late-aughts, when Joomla, Drupal, and WordPress were all pretty similar in terms of install base, WordPress was just simpler to start with and become familiar due to its abundant documentation.
The non-code thing I want most for my open source projects is very simple: I want people to use them, and then publish some kind of note about what they used them for.
This can come in almost any form. A message on the project's Discord channel. A tweet or toot or other short-form message. A screenshot. A gist. A public GitHub repo, ideally with a descriptive README. A YouTube or TikTok video.
Anything like this is SO valuable for a project:
1. It shows people actually using the thing, which is motivational for the developers and also provides social proof to other people considering trying it out
2. It provides feedback. Just seeing what people are building helps show which features matter the most, and often highlights other things like what features were less obvious.
3. It's just nice. Seeing people use my stuff is why I build it. That's motivational again, but I said it twice because it's so important.
Agree. I am in the process of launching a new Open-Source project for Civil/Mechanical/Chemical engineers. In my gut feelings, this software shall be used by at least 10x Engineers compared to the number who may actually help code it. So, there must be a way for those Users to contribute back to the project. Even if it is simply improving the docs. If I use a static site generator such as Hugo to generate the docs (EDIT: user manual in our language), there must be a way for users (not developers) to submit correction/updates to the docs. I can't expect them to create a GitHub issue either, so I have to think about a way to do this. i.e. In this case, non-code contributions are far more important than the actual pull request.
> am in the process of launching a new Open-Source project for Civil/Mechanical/Chemical engineers
I'm in this group (I'm a Materials/Chem eng). We have recently started using media wiki internally for all sorts of documentation related things it has taken off very quickly.
Over the years there has been other solutions pushed onto us like confluence and sharepoint those never really gained any traction.
Having plugins enabled (like math equation editor) is important - Engineering documentation involves Math equations. The wiki lets you use markup like this "\frac{dC}{dO} = \frac{10}{\alpha+\frac{\beta}{([C]-C_{min})^{DC}}}" but also has visual editor.
Excellent. Same here. I have got Media Wiki installed in one of our internal servers and currently in the processes of updating the configurations to comply with Security Auditor requirements. I hope it takes off similarly over here.
This. An e-mail based workflow is much better for non-developers because you don't really need to create an account and faff around with an unfamilar plaform, it's just e-mail.
The issue then becomes using a good local VCS UI and also a good remote UI. I'm not familiar with Guix, but sourcehut, despite not being quite there yet, has lots of potential imo.
Side note:
Unfortunately, it seems like development has slowed down. I see some activity in the mailing lists, but there hasn't been a "What's cooking" post in ages, nor have I noticed any real changes in a while. @drewdevault @emersion what's going on?
If you are getting non-code contributions, that likely means you have non-technical people who both understand your project AND find value in it. Which is a good indicator that your project will be successful regardless.
This is me, a "non-coder" blue-collar IBEW electrician (retired).
Twenty years ago, while using a really cool open source project [written by ESL programmers], I emailed the team and offered my own English revisions to their initial documentation attempts.
Even today [without any further contributions], I'm one of ten people in the "special thanks to" section of their project, which has 100m+ downloads to date, and has updates from hundreds of contributors.
I'm not sure why "I'm so special" [to still be thanked], but I do list this under the copyediting section of my resumé [because the software is well-known].
Perhaps a little cynically, but partly based on similar credits on software I maintain: because the current maintainers aren't quite sure what you did any more, and don't want to cause a problem by removing your name.
There is an inflection point, where a product goes from unknown and used by hard core fans, to becoming known and looking for more users, where documentation is key. You will have a very hard time crossing this point without good docs.
This reminds me to write the user guide for Neural Amp Modeller. It's definitely at this inflection point and the docs need some love!
With some years under my belt now working as a software engineer, I've learned that these non-code elements are hugely important in getting people to adopt your work. I used to just code up something and tell my team about it, either through messaging, email, or even a presentation. There would be very little traction. Some time later, someone would mention a problem and I would tell them about my project. Then it may gain some traction.
The "secret" I've learned is to not only build the project but pave the road so that it's ridiculously easy for someone to adopt it. This means top notch documentations with screenshot and links or scripts that automate the task of setting it up. It probably doubles the work involved but it's way better than coding something up and no one using it.
Community and docs are 100% a driver of growth but its a flywheel, you can't have them unless you have a project people care enough about to join a community for.
The last two companies I’ve worked for have had their documentation on GitHub to have PRs made against and I can say first hand how powerful it is to allow users to catch old documentation and just push a change
It makes the lives of Tech Writers, PMs, and engineers so much easier, and enables the community around your software to get more involved and feel like they made an impact
As an open source database Milvus contributor, I am deeply grateful for the contributions brought by all non-code contributors to the project. However, in my view, this is far from sufficient. Without the project maintainers or dedicated documentation developers to operate the official website, you will soon find the documentation filled with a lot of outdated information, misconceptions, and some incorrect understandings. More crucially, if core contributors do not deeply participate and draft the first version of the functional documentation, it is likely to be very difficult to read because it would lack the mental model documents that explain how the authors think about things. In fact, aside from simple user documentation, a good FAQ can help others better understand the design, and this must be the responsibility of the core developers.
I used to be active in a few distributions 20 years ago – when I still had time for that – and I also feel documentation and general news and changelog reporting are absolutely crucial. We can come up with the greatest code and technical solutions; if nobody knows about them, all that work will go unused. Clearly communicating simple facts such as what it is, how it can be used, where a project is going, what its trade-offs are, contributes to the "friendliness" factor around a project.
I used to be rather critical about the identity groups approach some projects got into – we're all in the same project after all – but truth is that it's very important for open-source software to attract people that don't think of themselves as hardcore hackers because without that more diverse skill set, a project is just a proverbial tree falling in the forest.
Open Source or not you need someone or few someone, preferably dictatorial on top who have a cohesive vision of what they are making and who they are making it for. They should be a good communicator to sell more people to that vision and lot of luck because you'll still fail for multiple reasons.
I think the community building component is the most interesting here. How do projects rally the contributors necessary to take a complex, long-term, poorly documented project to the next level - versus them being turned away by the dire state of non-code things (looking at you NixOS)?
> “The things you need for a successful open source project overlap with what you need for a successful commercial product,” [..] “That includes documentation, localization, marketing, graphic design, testing, community management, and release management.”
Most open source software has none of that. If you want it to be popular, and sit around smelling your own farts because of how many GitHub Stars your project has, then all that's great. Absolutely unnecessary to make open source that people will use.
Just keep committing, be easy to contact, make it stupid easy for people to contribute, and rapidly iterate on contributions (do not let PRs and issues sit for months or wait months to reply to an e-mail). Mailing lists, chat rooms and forums are all good ways to allow other people to solve problems ad-hoc. Avoid anything that attracts spam.
Personally I find "corporate" open source very annoying. There's often 3 different websites and the docs are buried somewhere deep. Yeah you have a great mascot and splash page, but I'm an actual developer trying to solve an actual problem. When I do find the docs website, the docs I want aren't even on the website, they're somewhere in the repo. The README doesn't tell me where, though, it's just another splash page that doesn't even link to the docs website. Oh, I need to jump through 15 hoops to join your private Slack to ask you a question? Oh, I need to sign up for your weird private Jira instance to submit a bug? Sign away my life with this weird contributor agreement? Screw it, i'll use a different project.
I wonder how LLMs will fit into this, or about hackable environments versus binary options. Will there be a pip version of the documentation for noobs that are RAG trained phi-2 that can manipulate the computer via terminal?
The binary option I think of is not needing any documentation like for the one click jailbreaks means that it probably doesn't need much documentation.
Definitely prefer the GitHub pages that assume you don't know how to install and makes it stress free versus something like sway and configuration, do people end up with Manjaro instead.
I've been acting as product manager for the past year on primatejs...and despite tooting my own horn (and of course the dev implementing my suggestions), the framework is now on par with most major frameworks I've used over the last 15 years.
It's a great thing to do, I get the warm fuzzies when I help someone on a mailing list,even on big projects like Apache Spark, I'm not the smartest guy and can't help write a query planner but if I can help someone fix a bug it's good enough for me
1000 percent, this is something I've been paying more and more attention to recently.
The reason why Blender is on a trajectory to very slowly take over the industry and Gimp isn't is because Blender has a community of non-coding artists who are on good terms with the dev team and who talk about the product, build tutorials, and generally make it accessible. The shift in how people thought about and talked about Blender is in no small part influenced by people throwing tutorials on Youtube saying "check out this cool thing I made in Blender, here's how you do it."
Similarly, the reason why Mastodon is eclipsing other Twitter competitors like BlueSky and why it's more successful than arguably much better federated protocols like Matrix is because a bunch of non-coders showed up on Mastodon and turned it into a community (with all the good and bad that entailed).
I have so many issues with ActivityPub, it is not the protocol I would have preferred to win the federation debate. I don't want to badmouth Mastodon, it's a huge achievement and I would in no way do a better job building it -- but my point is Mastodon can have no concept of mobile identities or homeserver separation, and lack support for E2EE, and be lagging on moderation tools, and be arguably not fantastic about handling accidental DOS attacks on smaller instances, and it just does not matter at all, because they got a community to show up that likes them and that is enthusiastic and that helps with all the non-code stuff and actively goes out and evangelizes them and says "oh, join my instance, I'll show you how to set up filters and who to follow", and so... that's it, that ends up mattering more; because of that community involvement ActivityPub is now getting federation support from Wordpress and Threads.
----
Getting actual adoption of Open Source products is about more than code. If someone is showing up on the Linux forums and helping randos solve tech problems, that person is contributing just as much as someone who writes code for the kernel. And not just contributing to the person you're replying to, you're also averting a distracting issue on a Github repo, you're making the community feel friendly, you're making someone on the fence think, "actually, I could give this Linux thing a try because if I get confused even if I feel like I'm being stupid somebody will jump in and be happy that I'm here and will try to help me". You're taking care of a support issue so that a moderator or another helper or an overworked community manager that has seen hundreds of identical comments no longer needs to worry about it.
It is a valuable contribution to help others use Free/Libre software, to write documentation, to be public about your usage of Open Source software and to talk about the things you make with it, to brainstorm ideas and give feedback on features, and even just to cheer on developers, donate money, and to get excited about releases and excited about the things they're doing.
Even the bikeshedding that happens on platforms like Mastodon -- while it's good to have tiered systems of feedback that shield developers from getting harassed by thoughtless ideas or suggestions, it also helps Mastodon a lot to have a community of people who are constantly thinking, "hey, we should do X, we should do Y, Z is an issue we need to address." Filtering that into useful feedback is just triaging.
Others have pointed out, just documentation alone is a huge boon for getting people to actually use software. But going beyond that, I feel like increasingly I can predict what the health of a project is going to be in a few years based just on, "is there an enthusiastic community of non-programmers who are participating in the development process?"
As a new user of libcurl, I was recently able to quickly implement FTP upload and adapt it to our specific use case thanks to their tutorials and API documentation. I was even made aware of the lack of thread safety in old versions thanks to that same documentation, so I could warn my team that we should update.
Documentation is bloody important. Almost as important as the code and the test suite themselves.
[1]: https://monocypher.org