If you're interested in audio, PortAudio is an established project with a lot of users. I have no doubt that the docs could be improved. I know this because I wrote a large chunk of the docs and I am frequently impressed by the docs of other projects. I'm not sure what the best way to improve them would be (improve structure? replace missing content? presentation? unify doxygen docs, README, and website, something else?). You could make an impact by reviewing our docs and posting your review as a GitHub ticket with a prioritised list of low-effort, low-churn, high-impact improvements. Even better if you submit some PRs. At the moment us maintainers have to allocate most of our limited time to maintenance.
I'd also like to make a general comment about "making an impact" on open source projects. There are many ways to help out on an open source project, but one good way is to maximise the benefit:maintainer-cost ratio. Maintainer cost comes in a number of forms: cognitive and time cost of reviewing PRs, engaging in design discussions, iterating on PRs, coordinating a "live" work in progress PR for long periods of time, you get the idea. With this in mind, I like it when the contributor owns the PR from submission to merge, don't just make the PR, help the maintainers get it over the line however is needed. A lot can be done by simply submitting PRs that follow project guidelines and established conventions, are targeted at a single improvement, making them uncomplicated, quick and easy to review, and most importantly such obvious improvements that there is no question about merging the change. A pet peeve of mine is PRs that include one excellent insta-merge change and an unrelated change that is controversial or requires significant rework. Keep PRs orthogonal, atomic, simple. It might be more work for you but if you are available to contribute you are not the time-poor party.
I came here to say something like "This is a joke, right?" Not to be snarky, but because I just assume everyone throws the Inevitable Looming Tool at docs, especially where resource is scarce.. but this point has already come up and I suppose there is some truth in the idea that folks detect AI and are often put off by it - but while I think that's true in creative/blog pieces, is it really true in formal docs? For me that is in the same column as cancer cures, gene comprehension, room temperature fusion wrangling etc. - the 'lets-get-AI-onto-it-pronto' column...
Anyway, my vapid observations aside, I have a couple of related questions:
- I too would be willing, even keen, to contribute to good documentation of FOSS projects that need it and that I am interested in - a huge barrier to me is that a person needs sufficient understanding to really contribute, don't they? To the point that you pretty much need to get into the code quite deeply or else endlessly pester committers to explain how it works? OK, I am generalising, but it seems valid in the main. A while ago, I observed on a relevant list that the libvirt documentation of how to take qemu snapshots was amazingly fragmented, inconsistent and out of date and this led to comments that I should step up and produce some PRs - but my whole point was that this sh1t is hard to understand without very good docs! I would barely know where to start and I would be very hesitant about making definitive statements...
- As for improving doc structure - and this is a serious consideration as soon as you sit down to think about this stuff - I came across and adopted the https://diataxis.fr/ framework a few years ago.. I have to say the uptake among my co-workers has been dismal. Can anyone suggest doc frameworks or approaches that are more motivating, have less friction, whatever?
Yes! I recently started maintaining https://github.com/AnalogJ/scrutiny a self-hosted service for collecting and monitoring hard drive SMART data. Right now the docs are just a somewhat organized collection of markdown files in the repo. It would be great to have something more polished, rendered by GitHub pages, etc, but I have been prioritizing bug fixes and don't have the bandwidth (or expertise really) to improve the docs.
The latest release has ~500k downloads so it's a popular project and your contribution would be a pretty significant impact.
Whenever someone posts AI-written content, at least half the comments on this site are calling it out and saying they stopped reading. I think it's obvious at this point that AI has a certain writing profile, which includes blandness and punchy statements that are thin or vapid on inspection.
If you're interested in audio, PortAudio is an established project with a lot of users. I have no doubt that the docs could be improved. I know this because I wrote a large chunk of the docs and I am frequently impressed by the docs of other projects. I'm not sure what the best way to improve them would be (improve structure? replace missing content? presentation? unify doxygen docs, README, and website, something else?). You could make an impact by reviewing our docs and posting your review as a GitHub ticket with a prioritised list of low-effort, low-churn, high-impact improvements. Even better if you submit some PRs. At the moment us maintainers have to allocate most of our limited time to maintenance.
Daily snapshot of the generated doxygen docs are here: https://files.portaudio.com/archives/pa_v19_doxydocs.tgz
website: www.portaudio.com
GitHub (including wiki): https://github.com/PortAudio/portaudio
I'd also like to make a general comment about "making an impact" on open source projects. There are many ways to help out on an open source project, but one good way is to maximise the benefit:maintainer-cost ratio. Maintainer cost comes in a number of forms: cognitive and time cost of reviewing PRs, engaging in design discussions, iterating on PRs, coordinating a "live" work in progress PR for long periods of time, you get the idea. With this in mind, I like it when the contributor owns the PR from submission to merge, don't just make the PR, help the maintainers get it over the line however is needed. A lot can be done by simply submitting PRs that follow project guidelines and established conventions, are targeted at a single improvement, making them uncomplicated, quick and easy to review, and most importantly such obvious improvements that there is no question about merging the change. A pet peeve of mine is PRs that include one excellent insta-merge change and an unrelated change that is controversial or requires significant rework. Keep PRs orthogonal, atomic, simple. It might be more work for you but if you are available to contribute you are not the time-poor party.
I came here to say something like "This is a joke, right?" Not to be snarky, but because I just assume everyone throws the Inevitable Looming Tool at docs, especially where resource is scarce.. but this point has already come up and I suppose there is some truth in the idea that folks detect AI and are often put off by it - but while I think that's true in creative/blog pieces, is it really true in formal docs? For me that is in the same column as cancer cures, gene comprehension, room temperature fusion wrangling etc. - the 'lets-get-AI-onto-it-pronto' column...
Anyway, my vapid observations aside, I have a couple of related questions:
- I too would be willing, even keen, to contribute to good documentation of FOSS projects that need it and that I am interested in - a huge barrier to me is that a person needs sufficient understanding to really contribute, don't they? To the point that you pretty much need to get into the code quite deeply or else endlessly pester committers to explain how it works? OK, I am generalising, but it seems valid in the main. A while ago, I observed on a relevant list that the libvirt documentation of how to take qemu snapshots was amazingly fragmented, inconsistent and out of date and this led to comments that I should step up and produce some PRs - but my whole point was that this sh1t is hard to understand without very good docs! I would barely know where to start and I would be very hesitant about making definitive statements...
- As for improving doc structure - and this is a serious consideration as soon as you sit down to think about this stuff - I came across and adopted the https://diataxis.fr/ framework a few years ago.. I have to say the uptake among my co-workers has been dismal. Can anyone suggest doc frameworks or approaches that are more motivating, have less friction, whatever?
Yes! I recently started maintaining https://github.com/AnalogJ/scrutiny a self-hosted service for collecting and monitoring hard drive SMART data. Right now the docs are just a somewhat organized collection of markdown files in the repo. It would be great to have something more polished, rendered by GitHub pages, etc, but I have been prioritizing bug fixes and don't have the bandwidth (or expertise really) to improve the docs.
The latest release has ~500k downloads so it's a popular project and your contribution would be a pretty significant impact.
If you’re interested in finance and investment tracking https://github.com/afadil/wealthfolio
Perhaps one of the pages gathering projects that need help will be inspiring for you, i.e.: https://up-for-grabs.net/#/filters?date=6months&labels=&tags... or https://www.codetriage.com/ ?
docs.yjs.dev
I'm currently working on a major rewrite and it would be great to start off with great documentation!
It might be interesting to explain new concepts in the field of collaborative editing (e.g. how to attribute content).
Feel free to pm me at: hi@kevinjahns.de
Come spend some time with the TaxonWorks community, docs can always use love. https://taxonworks.org.
https://github.com/git-bug/git-bug if that's your thing.
https://taler.net/ would be happy to get help.
Just out of curiosity, what would be the difference between what you write and what AI writes?
Whenever someone posts AI-written content, at least half the comments on this site are calling it out and saying they stopped reading. I think it's obvious at this point that AI has a certain writing profile, which includes blandness and punchy statements that are thin or vapid on inspection.
a