8 ms·

Non-code contributions to open source

344 points by keepamovin 3y ago

tracerbulletx 3y ago
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.
keepamovin 3y ago
This was interesting because I never even thought of that. But looking back on my experience it makes a lot of sense.
- cranberryturkey 3y ago
  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.
bell-cot 3y ago
Lordy, yes. And not just open source.
deleted 3y ago
[deleted]
coldtea 3y ago
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 3y ago
  Couldn't agree more. This reminds me of the codes of conduct hell from a few years ago.
  - zilti 3y 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.
    - beeboobaa 3y ago
      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 https://github.com/opal/opal/issues/941 [2] https://github.com/nixxquality/WebMConverter/commit/c1ac0baac06fa7175677a4a1bf65860a84708d67 https://github.com/nixxquality/WebMConverter/commit/c1ac0baa...
      - pavlov 3y ago
        [flagged]
        ad404b8a372f2b9 3y ago
        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 3y ago
        [flagged]
giamma 3y ago
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/ https://www.eclipse.org/contribute/
blackoil 3y ago
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.
eszed 3y ago
> 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.
- NoboruWataya 3y ago
  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.
rq1 3y ago
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.
loup-vaillant 3y ago
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 https://monocypher.org
- SAI_Peregrinus 3y ago
  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.
  - deleted 3y ago
    [deleted]
  - zilti 3y ago
    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 3y ago
    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 3y ago
    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 https://www.ramijames.com/thoughts/docs-deserve-more-respect
ramshanker 3y ago
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.
- dsgnr 3y ago
  [dead]
- m463 3y ago
  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 3y ago
    Guix does it right, and Sourcehut as well. No accounts or captchas, just mail in the patches.
    - Tmpod 3y ago
      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?
Intermernet 3y ago
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!
samsquire 3y ago
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
- ivanjermakov 3y ago
  Adding to the list: * Approachable CONTRIBUTING.md with a brief technical overview and suggestions on how to get started.
- dpkirchner 3y ago
  * functional, tested example code
- matheusmoreira 3y ago
  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.
gavinhoward 3y ago
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.
cloudripper 3y ago
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)?
georgestephanis 3y ago
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.
hangonhn 3y ago
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.
danShumway 3y ago
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?"
test6554 3y ago
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 3y ago
  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 3y ago
    > 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.
graphe 3y ago
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.
wvh 3y ago
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.
smfjaw 3y ago
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
charliebwrites 3y ago
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
0xbadcafebee 3y ago
> “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.
simonw 3y ago
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.
aetherspawn 3y ago
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?
redskyluan 3y ago
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.

344 points by keepamovin 3y ago

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.

keepamovin 3y ago

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

cranberryturkey 3y ago
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.

bell-cot 3y ago

Lordy, yes. And not just open source.

deleted 3y ago

[deleted]

coldtea 3y ago

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 3y ago
Couldn't agree more. This reminds me of the codes of conduct hell from a few years ago.
- zilti 3y 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.
  - beeboobaa 3y ago
    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 https://github.com/opal/opal/issues/941 [2] https://github.com/nixxquality/WebMConverter/commit/c1ac0baac06fa7175677a4a1bf65860a84708d67 https://github.com/nixxquality/WebMConverter/commit/c1ac0baa...
    - pavlov 3y ago
      [flagged]
      - ad404b8a372f2b9 3y ago
        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 3y ago
        [flagged]

giamma 3y ago

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/ https://www.eclipse.org/contribute/

blackoil 3y ago

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.

eszed 3y ago

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

NoboruWataya 3y ago
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.

rq1 3y ago

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.

loup-vaillant 3y ago

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 https://monocypher.org

SAI_Peregrinus 3y ago
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.
- deleted 3y ago
  [deleted]
- zilti 3y ago
  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 3y ago
  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 3y ago
  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 https://www.ramijames.com/thoughts/docs-deserve-more-respect

ramshanker 3y ago

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.

dsgnr 3y ago
[dead]
m463 3y ago
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 3y ago
  Guix does it right, and Sourcehut as well. No accounts or captchas, just mail in the patches.
  - Tmpod 3y ago
    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?

Intermernet 3y ago

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!

samsquire 3y ago

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

ivanjermakov 3y ago
Adding to the list: * Approachable CONTRIBUTING.md with a brief technical overview and suggestions on how to get started.
dpkirchner 3y ago
* functional, tested example code
matheusmoreira 3y ago
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.

gavinhoward 3y ago

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.

cloudripper 3y ago

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

georgestephanis 3y ago

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.

hangonhn 3y ago

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.

danShumway 3y ago

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

test6554 3y ago

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 3y ago
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 3y ago
  > 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.

graphe 3y ago

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.

wvh 3y ago

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.

smfjaw 3y ago

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

charliebwrites 3y ago

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

0xbadcafebee 3y ago

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

simonw 3y ago

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.

aetherspawn 3y ago

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?

redskyluan 3y ago

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.