Non-code contributions to open source | Hacker News Reader

Non-code contributions to open source

github.com

344 pointskeepamovin124 comments

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

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.

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.

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.

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

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

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.

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.

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.

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.

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

https://github.com/stoeffel/elm-verify-examples

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

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

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

> Monocypher is an easy-to-use crypto library.

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 warrior does not trifle with secret messages! Have you no honour?

Edit: Oops, replied to the wrong user. Diplacing it here: https://news.ycombinator.com/item?id=39375470

I think you misunderstood my comment. I'm not saying that I don't understand what your library does.

Oh crap, I meant to reply to @LtWorf, and somehow botched it. I’m moving my comment, let’s say no one will ever know.

I won't tell if you don't ;)

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

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

Adding to the list:

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

* functional, tested example code

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.

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

Couldn't agree more.

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

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]

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

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

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.

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

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

im looking to jump, explain honkey

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

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

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?

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

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?

Just try Ansel. I saw this topic a while ago. https://news.ycombinator.com/item?id=38390914

I am only familiar with his YouTube, and then this topic. https://github.com/aurelienpierreeng/ansel Here are his examples.

It seems 1:1 compatible when I switched.

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

just don't accept the PR?

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

Don't forget the mob that some of these personalities can unleash upon you if you show yourself to not be aligned with their views.

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

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.

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.

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.

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.

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

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.

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.

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

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.

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

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

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

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

Your story is from 1996 and 1997.

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

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

More recent example:

https://github.com/kovidgoyal/kitty/issues/879

> 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!

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

Not to mention an obscenely expensive lifestyle.

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.

So definitely a double-edged sword.

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.

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/

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.

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.

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

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?

Create a Wiki :)

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

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

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

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.

Lordy, yes. And not just open source.

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

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.

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

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

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

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?

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.

Reply on news.ycombinator.com