return to table of content

Non-code contributions to open source

coldtea
52 replies
1d5h

Not so sure.

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

LunaSea
17 replies
1d5h

Couldn't agree more.

This reminds me of the codes of conduct hell from a few years ago.

zilti
14 replies
1d5h

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.

beeboobaa
12 replies
1d5h

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]

[1] https://github.com/opal/opal/issues/941

[2] https://github.com/nixxquality/WebMConverter/commit/c1ac0baa...

pavlov
10 replies
1d4h

You don’t have to use GitHub and they don’t have to host your insults. It’s free enterprise.

ad404b8a372f2b9
7 replies
1d4h

Just like I'm free not to use Whatsapp, as long as I don't mind not being able to contact most of my family and friends.

And I'm free not to use Facebook, as long as I don't mind not having access to specific medical support groups which are only available there.

And Cloudflare, as long as I can stop using most modern websites.

And so on, you get my point.

Intermernet
6 replies
1d3h

You can use whatever you like. They can also kick you off whenever they want. What bit of this is difficult to understand? Is the "free market" not free enough? The general rule is to respect other people. If you start trying to dehumanise or "other" people, don't be surprised when you get shut out.

zilti
3 replies
1d1h

Those mentioned platforms are big enough that it is not a free market anymore. Guess why the EU is going after them one-by-one.

mianos
2 replies
21h15m

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.

ThunderSizzle
1 replies
19h14m

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.

mianos
0 replies
18h27m

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.

coldtea
0 replies
1d1h

You can use whatever you like. They can also kick you off whenever they want. What bit of this is difficult to understand?

The "bending over and taking it" bit.

I don't believe platforms of a size and above should be treated to "they can do whatever they like" / "it's their way or the highway" standards.

I do believe users should have more dignity than to accept that.

Pannoniae
0 replies
1d3h

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

coldtea
1 replies
1d1h

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

indigochill
0 replies
1d

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

rockskon
0 replies
22h34m

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.

matheusmoreira
0 replies
12h12m

Don't worry, people archived quite a lot of it. As did I.

https://news.ycombinator.com/item?id=21386948

The GitHub issue I linked is gone but those archive links are still up.

Never forget the fact they laughed in people's faces when they tried to hold them accountable to their own rules.

This brutal article also came to mind:

https://zedshaw.com/blog/2020-10-07-authoritarianism-of-code...

beeboobaa
1 replies
1d5h

If nothing else, that while ordeal has shown you can get a job at GitHub even if your only marketable skill is harassing people.

red-iron-pine
0 replies
22h18m

im looking to jump, explain honkey

elzbardico
12 replies
1d3h

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.

lolinder
6 replies
1d2h

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.

red-iron-pine
4 replies
22h20m

perception is reality, and there have been a few high profile cases of people injecting politics into the discussion.

lolinder
2 replies
21h44m

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.

keybored
1 replies
20h9m

How is bug fixing a non-code contribution? You didn’t say bug reporting.

lolinder
0 replies
19h49m

Oops, yes, that was a mistake, I meant bug reporting. Fixed.

wolverine876
0 replies
12h39m

perception is reality

How does that apply here? That applies when people act on their perceptions; here we are talking about what the reality is.

elzbardico
0 replies
1d2h

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.

woodruffw
3 replies
1d1h

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.

[1]: https://invisible-island.net/ncurses/ncurses-license.html

cvwright
2 replies
22h44m

Your story is from 1996 and 1997.

Of course all the bickering was between technical people — those were the only people around!

matheusmoreira
0 replies
12h26m
lolinder
0 replies
22h33m

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.

[0] https://github.com/rust-lang/team/pull/671

wolverine876
0 replies
12h37m

attack vector

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!

beardicus
4 replies
1d5h

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?

mianos
2 replies
21h13m

But that is the issue. They won't be allowed to ask them to leave.

unleaded
1 replies
18h38m

just don't accept the PR?

mianos
0 replies
17h46m

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

graphe
0 replies
1d

No they aren't. See darktable and Ansel. I will never use darktable again. https://ansel.photos/en/

NoboruWataya
4 replies
1d4h

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.

coldtea
3 replies
1d1h

How could non-developers force changes to the UX? That requires changes to the code, no?

Or they could just give mockups, like in Gnome, Mozilla, and elsewhere, and have enough traction within the project to push for them.

danShumway
2 replies
21h55m

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.

coldtea
1 replies
19h24m

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.

danShumway
0 replies
18h2m

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.

elric
3 replies
1d4h

*cough* Thunderbird *cough*.

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.

NoboruWataya
1 replies
1d4h

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.

red-iron-pine
0 replies
22h15m

doesn't even have to be non-technical, just something not normally in your domain.

a lot of documentation is put together as part of some KT handoff, and is written by technical folks in that domain, for folks in that domain.

zilti
0 replies
1d1h

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.

asoneth
2 replies
1d5h

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.

coldtea
1 replies
1d3h

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.

lolinder
0 replies
1d2h

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.

tjpnz
0 replies
1d5h

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.

https://github.com/ayojs/ayo

lolinder
0 replies
1d3h

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.

keybored
0 replies
20h10m

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.

RobotToaster
0 replies
1d2h

Just look at what having a Lawyer with a political axe as a leader did to mozilla.

loup-vaillant
13 replies
1d4h

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.

[1]: https://monocypher.org

SAI_Peregrinus
7 replies
1d1h

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.

abdullahkhalids
1 replies
18h26m

You can put tests in python's class/method docs. They work wonderfully if you put enough examples to cover most inputs/outputs of the function.

SAI_Peregrinus
0 replies
17h9m

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.

Just_Harry
1 replies
23h50m

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.

E.g. the examples for the D standard-library's `curry` function are just unit-tests: the docs: <https://dlang.org/phobos/std_functional.html#quickindex.curr...>; the code: <https://github.com/dlang/phobos/blob/42b8c65ccfd35c863f7cedf...>

hitchstory
0 replies
22h51m

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.

zilti
0 replies
1d1h

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.

rqtwteye
0 replies
1d

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.

ramijames
0 replies
1d

This is ALWAYS TRUE.

Software without good documentation pales in comparison to software with good documentation.

https://www.ramijames.com/thoughts/docs-deserve-more-respect

LtWorf
3 replies
21h14m

I opened your link and don't know what it does.

bo0tzz
2 replies
21h7m

It says what it does in the first sentence on the page.

Monocypher is an easy-to-use crypto library.
marcellus23
1 replies
21h5m

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.

jholman
0 replies
43m

A warrior does not trifle with secret messages! Have you no honour?

actionfromafar
0 replies
1d1h

My heart skipped a beat when I saw there are PicoLisp bindings!

ramshanker
6 replies
1d4h

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.

m463
2 replies
1d4h

I would like frictionless contribution.

I know projects have to protect themself, but creating an account, or entering an email address or filling out a captcha is friction

maybe enter comment in this form and click to submit feedback.

zilti
1 replies
1d

Guix does it right, and Sourcehut as well. No accounts or captchas, just mail in the patches.

Tmpod
0 replies
17h12m

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?

bigger_cheese
1 replies
17h2m

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.

ramshanker
0 replies
3h12m

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.

Closi
0 replies
1d4h

Create a Wiki :)

samsquire
3 replies
1d3h

Things I want:

* lots of screenshots

* a README.md that is extremely long and detailed

* tutorials, reference, design documents, architecture diagrams

* mental model documents to explain how things are thought of by the authors

matheusmoreira
0 replies
12h32m

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.

ivanjermakov
0 replies
1d1h

Adding to the list:

* Approachable CONTRIBUTING.md with a brief technical overview and suggestions on how to get started.

dpkirchner
0 replies
22h44m

* functional, tested example code

eszed
3 replies
1d4h

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.

belval
1 replies
1d1h

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.

So definitely a double-edged sword.

georgestephanis
0 replies
1d1h

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.

NoboruWataya
0 replies
1d4h

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.

test6554
2 replies
1d

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.

ProllyInfamous
1 replies
22h32m

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

Symbiote
0 replies
21h3m

I'm not sure why "I'm so special"

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.

keepamovin
1 replies
1d8h

This was interesting because I never even thought of that. But looking back on my experience it makes a lot of sense.

cranberryturkey
0 replies
1d7h

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.

wvh
0 replies
23h3m

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.

tracerbulletx
0 replies
1d

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.

smfjaw
0 replies
22h32m

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

simonw
0 replies
20h1m

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.

rq1
0 replies
1d4h

Don’t you need something, like code, to write or comment on to begin with? Or do you create contributions on non existant things out of the blue?

What about documentations and other assets that can be code too? What about outdated assets?

Whenever I encounter these kind of discussions, it looks like someone’s trying to reinvent formal specs.

So big no. The most important part and the “secret” to open source success is open source code.

redskyluan
0 replies
15h52m

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.

hangonhn
0 replies
1d

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.

graphe
0 replies
1d

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.

giamma
0 replies
1d5h

I don't know if they are the secret to success, but I agree that non-code contributions are extremely important.

For example, the Eclipse Foundation often reminds users that bug reports are valuable contributions [1].

[1] https://www.eclipse.org/contribute/

georgestephanis
0 replies
1d1h

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.

gavinhoward
0 replies
1d2h

I have had more people praise my documentation than my code in my most famous project.

And this is for a standard POSIX utility! Docs are not really needed for those, right?

Well, apparently yes. Although what they praise is my documentation for developers in case I get hit by a bus.

You never know what will make people love your project.

danShumway
0 replies
1d

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?"

cloudripper
0 replies
1d2h

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)?

charliebwrites
0 replies
22h7m

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

blackoil
0 replies
1d4h

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.

bell-cot
0 replies
1d7h

Lordy, yes. And not just open source.

aetherspawn
0 replies
18h40m

I love the style of the illustrations in this blog post (and this blog in general). Does anyone have any ideas for Dall-E prompts to reproduce it?

Intermernet
0 replies
1d3h

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!

0xbadcafebee
0 replies
22h1m

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