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

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

@dave
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?

@dave
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 😞

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

@dave
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 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...
please hear...

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

Follow

@onepict @paolo By the way, when you load it, it alternates between the 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...

· · Web · 1 · 0 · 0

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

@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 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...
please hear...

@dave
Yeah, it may have been easier if they had specified the specific git commit. Although I suspect they weren't sure which one would be suitable for you. Perhaps respond, restate the ubuntu release part and the current contents of the config file as you aren't sure which commit is suitable. It can be difficult for developers responding to support requests when in the middle of coding. This happens with the bigger projects as well, even with paid support/dev tiers.

I'm not a developer but it's really tricky switching from infrastructure stuff to support and triage. It's a different mind set where you are trying to get the most relevant information from the client, or to the developer.

@onepict @paolo This is starting to deviate away from the original subject... But, in fact, Paolo, application of the solution in the resolving commit (github.com/Chocobozzz/PeerTube) is difficult, because the names of the files edited in the codebase are not at all the same as the names of the files ultimately physically providing the executed code... So I say again that proper developer documentation would have been necessary to enable me to implement the patch...
PLEASE HEAR

@dave
Yeah, you might just need to really lay that out in the ticket. I know you shouldn't have to, you might need a separate ticket to illustrate its a documentation issue now.

@onepict No, we're getting off-topic now 😄 I can resolve this particular problem by re-installing my instance using a clone of the git master... but, the *real subject of interest* is that proper developer documentation is really necessary for a project like , which has a big dependent community but only one single developer... If we lose that dev, a whole community and a whole project is orphaned...
please hear...

@dave
Indeed, I think I switched context from my community brain to my support brain. LOL.

@dave The good thing of FOSS is that anyone can contribute and sometimes the best people to write code documentation are those that don't know the platform intimately.

You can start documenting what you understand and ask questions to fill up the gaps.
Once you started others will join in 😉

@onepict

@paolo @onepict No, I would have done it happily with the developer's collaboration, but I'm not going to single-handedly waste days trying to reverse engineer his code... I have a life, a wife and a guitar waiting for me 😄

@dave
Well a tech work life balance is important to avoid burn-out. I've been there, it's not fun. Especially when its something you love doing and you rationally know you love doing. 😊
@paolo

@dave I guess also those that are supposed to do that job haven't done what you'd like to have as they have a life as well @onepict

@paolo
It's always hard for small firms and projects to balance development, implementation and support. Especially when starting out small and folks need to wear many hats. Plus we all have good and bad days.
@dave

@onepict @paolo @dave

also for 10-20 years there has not been enough encouragement of teens/young adults into either sysadmin or dev work other than those who go via traditional route of University, when really this should start with high school and more organisations should encourage coders as young as their teens (even some FOSS orgs seem to only want graduates as interns) but without all the high pressure environment of bootcamps or those cursed job interviews USA tech cos carry out..

@vfrmedia
Yep, there wasn't a computer club in my high school and certainly not a FOSS club. So there's a recruitment need for computing teachers, who have quite alot on their plate as it is, if we wanted afterschool clubs.
@paolo @dave

@onepict

in England and Wales goodwill that teachers had for running after school clubs was lost around 1989/90 (when I was still in high school!) as Education Authorities held teachers liable for any safeguarding incidents that could happen, its even more of a minefield for outside visitors to a high school environment (I have to deal with it for my volunteer work in community radio).

Also cultural attitudes amongst youth imported from USA (nerds vs jocks) need to change>>

@paolo @dave

@onepict

what happens (even more so than when I was a lad decades ago) is those lads and lasses who are into tech get judged as "geeks/swots" and uncool, but often do quite well with qualifications and get better jobs later in life, but why /would/ they want to increase social equality for those who previously bullied them?

So perhaps not surprising they don't care about working for proprietary software company and/or adtech/surveillance...

@paolo @dave

@vfrmedia
I think it depends as well on the community around them, if you had a mentor who drummed in the idea of community and public services into and you respected them for it, I suspect it predisposes you to this.
@paolo @dave

@onepict

that is definitely true, I did work experience with British Telecom when they were still part nationalised and my mentor was this middle aged union activist chap who talked a lot about telecoms as a public service and a lifeline to seniors and those with health problems as any of the tech (today I work in IT/networking for health and social care organisations!)

@paolo @dave

@vfrmedia
At least at our hackerspace we run a Code Club for kids to teach them some basics but we should do more.

The issue is to find volunteers to do training on more complex things.

@onepict @dave

@paolo
Volunteers in the UK as you know can be tricky to find as I think there's some child protection requirements /qualifications you are meant to do as well? They are needed, I think that's one of the barriers to finding volunteers. I'm not sure about the rules in Europe.
@vfrmedia @dave

@paolo @vfrmedia @dave
At my uni we have industrial placements as part of the degree, but it is hard for the uni to find those opportunities for students.

@onepict

DBS check is relatively easy to get but you need to produce valid and original identity documents (so things might take longer if you aren't a UK citizen).

AFAIK its the task of the voluntary groups are to teach their volunteers the basics of safeguarding and make them aware of the organisations policy (on places like churches its nowadays uploaded to their website).

I think all European nations have something similar these days..

@paolo @dave

@vfrmedia @onepict @paolo These days it seems to be becoming more and more complicated to do volunteer projects...

@dave
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
Mastodon on Tardis World

Tardis World is just another node on the Mastodon federated social network. Feel free to sign up if you'd like to do your Mastodon socializing here.