#opensource software is not genuinely Open Source if there's no proper documentation for the source code.
#framasoft please hear...
#invidious please hear...

Do you mean how to install their software or do you mean how the code works?

@onepict Developer documentation is about how the code works... Installing the software is a subject for the user documentation...

So in what way are Framasoft and Invidious failing? Criticism is valid but it needs to be explicitly explained if you want the developers (one of who needs a rest, and there's alot of folk feeling left in the lurch) and the community to listen. Is it not just the documentation is it also a failure in communication by the developers?

@onepict When projects are developed by single developers, it's particularly important to have thorough documentation:

- to facilitate uptake for potential coding contributors;

- to ensure maintainability and possible continuation of the project, if the original developer falls by the wayside.

Proper developer documentation is even more important when projects seek to accumulate communities that become dependent on the software.

Doesn't that make sense?
#peertube #invidious #mastodev

Preaching to the choir here. I'm just trying to find a way to communicate that with others. We can't just sub toot it. We have to be explicit. Which may lead to some arguments.
Which I hate the idea of. I'd rather just have a discussion and have it lead to some form of consensus. But for it to get there in this space everyone's cards need to be on the table with explicit reminders of what the particular rules are.

@onepict Ahh, Esther, it's flogging a dead horse, anyway... I can post it in French, too... But it won't persuade those devs anyway 😞

I'm just hoping that perhaps one day when new developers/projects come along the points we make sink in. It does feel pointless occasionally, but I feel it's important someone states this. If nothing else it means if folk say "oh no one spoke up to us about this" there's a record that shows some of us have. If only to encourage more of the silent community who does agree but are scared to speak up to do so. It's a measure of a community on how it reacts to queries or criticism.

I know that to some developers this can seem like a side issue and pointless. But I don't get how we expect FLOSS projects to be utilised by laymen or folks outside our bubble if we can't make it compressible to them. Proprietary doesn't just win because of monetary resources, it's because there are resources so that any person can easily use/install their products. Regardless of privacy violations or how crap the product is.

@onepict For sure, if ne wanted to sell a package like #peertube to a commercial company, there's no way they'd accept it with the developer documentation it has.

Proper developer documentation would almost certainly be a contractual clause.

But even with software that's free but that accumulates a large dependence community, surely it's a bit of a moral obligation to properly document it so that the entire project is not dependent of one single human...
#framasoft please hear...

@paolo you got a Peertube instance going care to comment ?

@onepict @paolo By the way, when you load it, it alternates between the #peertube default white theme and my chosen instance dark theme, because of a bug, and because although there's already a patch on Github, I can't figure out how to apply it to the code installed on my server... That's because of lack of proper developer documentation...

Have you got the link to the issue with applying patch on github?

@onepict @paolo No, I filed an issue about the theming problem (github.com/Chocobozzz/PeerTube) and a fix was pushed... But the real issue is that the #peertube codebase is very complex, and it's very difficult to know what files to patch.... Whereas with proper developer documentation, it would be possible to figure that out...
#framasoft please hear...


Cleaning up documentation is also a major endeavour for any project. It's not something that's often funded either. Along with support which is seen as a cost, it's tied with documentation and better docco does reduce the support. We do know this, but it's hard to do when you are firefighting or trying to hit a specific deadline. As I said I really feel both sides of the argument on this. Especially when resources are constrained.

Sign in to participate in the conversation

chaos.social – a Fediverse instance for & by the Chaos community