11–17 of 17 posts
Just out of curiosity, what would be the difference between what you write and what AI writes?
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.
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?
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 m…