Improvement for Contribution.md

[gegeweb]

As discuted on #46 hompage will now be linked to the Contribution.mdpage. The content of this page is really succinct for the moment.

This page talk about two distincts things.

• contribution to the documentation (come from the link on the footer of the doc)
• contribution to the software himself

Perhaps it could be subdivised and linked to two distinct guidelines pages, one for contributing to the code, one for contributing to the documentation.

In introduction it must explain what is the differents channel of communication and contribution, especially explain the behavior of the forums on sourceforge.

I've some ideas. I can make a merge request if you agree (but before, I think I'll continue to work on the french translation when the first pages will be merged, I'm looking forward of it!).

[gilgongo]

In introduction it must explain what is the differents channel of communication and contribution,

This is probably our biggest issue, since we are rather unusual in having things spread across (and sort of overlapping) between GitHub, SourceForge and (to an extent) Facebook.

BTW in my opinion we should not encourage contributing to the docs if we are serious about clarity, structure and translations. If someone spots an error or has a suggestion, then let us know in a GitHub issue. If they need more help there is the forums (which we monitor).

[trebmuh]

BTW in my opinion we should not encourage contributing to the docs if we are serious about clarity, structure and translations. If someone spots an error or has a suggestion, then let us know in a GitHub issue. If they need more help there is the forums (which we monitor).

Can you please develop around that? It sounds strange to me as it is unusual in the FOSS realm to not encourage this kind of contribution. Might this be because the documentation website (and translations) is just starting and you don't want to be overloaded with things you're already working on?

[gilgongo]

Yes, I think there's a difference between actively inviting people to contribute to the docs, and accepting documentation submissions from people (with a process for that). The former implies that the project needs help, that there are missing parts, or some other problem. I think it would be hard to argue that we are in such a state. Jamulus is not a complex piece of software and our "coverage" in the docs is pretty good overall.

I think instead we are at a stage where we just need to firstly translate what we have, and then let what we have get read by enough people for us to see what needs incremental improvement. To spot some patterns emerging and address those in a way that we can manage over time.

So yes, overload is a potential problem - particularly for translation, but also because unlike software, documentation doesn't have to "compile", but it can develop serious bugs. Moreover, structuring documentation so that it reads coherently requires work not best approached by a swarm of people hacking at it. UI design is similar I think, and it's a bit of a cliche that FOSS projects exhibit low standards for both. You'll also notice that if you want to submit documentation to say, Tor, VLC, The Gimp or others (as I have) their processes are rather... unavailable compared to ours :-)

[trebmuh]

That make sense. So, what about redirecting people who would like to help to a forum where they can explain if they found a typo, if they think a documentation paragraph is missing, if they want to propose themselves for translation in a language,... Then from this forum, we could pick up relevant things?

[gilgongo]

Yes I think the GitHub issues here would be fine for that.

[trebmuh]

So, what about something around this for the page on the website:

• if you want to contribute code, go and present yourself and what you intention is at the Jamulus Software forge
• if you find a typo (in any language) on the website, go at the Jamulus Website repo and report it
• if you think a piece of documentation is missing on the website, go, at the Jamulus Website repo, present yourself, and explain carefully and precisely what is your use case, and describe roughly which piece of documentation is missing from your eyes

Thought?

[gilgongo]

Yes I think that's pretty much it. There's also a link Volker's manifesto for contributions that we could include: https://github.com/corrados/jamulus/issues/596

[gegeweb]

Yes I think the GitHub issues here would be fine for that.

Not sure.

The forum could be a good starting point, especially for those who don't have a Github account and don't have the skills to use it (which can be a barrier). If the idea is good and the person doesn't know or can't do on Github a team member can do it.

The beauty of free software is that everyone can and should be able to contribute, in their own way, with their skills. The same goes for the improvement of this documentation, which is already very complete, well-structured, pleasant to read and easy to understand. If I haven't already done so, thanks to the editors for that. It was very useful for me.

The proposal of @trebmuh seems to me to be a good starting point in this direction.

[gegeweb]

This is probably our biggest issue, since we are rather unusual in having things spread across (and sort of overlapping) between GitHub, SourceForge and (to an extent) Facebook.

Facebook should not be a communication channel for that. Too restrictive and constraining, not everyone has or wants to be present on this closed and centralised media. (IMHO)

[gilgongo]

@gegeweb Good point about the forum. So we should say post initially to the forum a rough idea, get it discussed, then they (or somebody else) post it to GitHub so it can be tracked later.

As to Facebook, for better or worse we have the Jamulus group there and it's pretty active, so some people like it at least :-). I too don't think we should put any documentation there, but it's being used similarly to the SF forums in terms of people posting questions and giving answers. BTW I think (but am not sure) that incoming links from Facebook might help our SEO.

[gilgongo]

@trebmuh

I'd render your suggestion as follows:

• If you want to contribute code, post your idea on the developer forum first so that it can be discussed before making a pull request.
• If you find a mistake, typo or something out of date (in any language) on the website, you can raise it as an issue here.
• If you think some documentation or information is missing or can be improved, post about that on the relevant discussion forum so that it can be discussed first.

[trebmuh]

Do we want to add Volker's manifesto for contributions in there? Proposition:

• If you want to contribute code, post your idea on the developer forum first so that it can be discussed before making a pull request (be sure to read main dev's Volker's manifesto for contributions)
• If you find a mistake, typo or something out of date (in any language) on the website, you can raise it as an issue here.
• If you think some documentation or information is missing or can be improved, post about that on the relevant discussion forum so that it can be discussed first.

[gegeweb]

Do we want to add Volker's manifesto for contributions in there? Proposition:

Yes we should.

* If you want to contribute code, post your idea on [the developer forum](https://sourceforge.net/p/llcon/discussion/developerforum/) first so that it can be discussed before making a pull request (be sure to read main dev's [Volker's manifesto for contributions](https://github.com/corrados/jamulus/issues/596))

* If you find a mistake, typo or something out of date (in any language) on the website, you can [raise it as an issue here](https://github.com/jamulussoftware/jamuluswebsite/issues).

* If you think some documentation or information is missing or can be improved, post about that on [the relevant discussion forum](https://sourceforge.net/p/llcon/discussion/) so that it can be discussed first.

Sounds good for me, clear and concise.

What about potential contributors who do not speak English or are not comfortable with? There may be one or more non-English speaking forums?

[gilgongo]

There may be one or more non-English speaking forums?

Yes, that should be possible if somebody wants to request it. SourceForge doesn't say if there's a limit on the number of forums we can have. I don't know if supports double-byte characters for when Jamulus gets popular in China though...

Do you want to put that wording on the changes branch and we can merge it in to translation with the next round?

[gegeweb]

Yes, that should be possible if somebody wants to request it. SourceForge doesn't say if there's a limit on the number of forums we can have.

There is a French Jamulus users group on Facebook where I'm on, I will be happy with a self-help forum in French. ;)

It allows users to help each other in their native language. The exclusive use of English can be discriminating, and this is not in the spirit of free software. (IMHO)

On the other hand I notice that many French-speaking users are discovering Jamulus (not only French people, I helped a French-speaking Canadian I met on my server recently, we chatted, but to play together he had too much latency).

I don't know if supports double-byte characters for when Jamulus gets popular in China though...

I hope that UTF-8 is now the standard and that everyone is using it! Since the time... ;)

[gilgongo]

There is a French Jamulus users group on Facebook where I'm on

If there's already one on Facebook, then is it wise to create another one on SourceForge as well?

[gegeweb]

If there's already one on Facebook, then is it wise to create another one on SourceForge as well?

Facebook implies that the person have a Facebook account. Some haven't or don't want have. A forum is more open. (IMHO)

As there is privative softwares vs free and open source softwares, Facebook is a privative "social network" vs the federated alternative softwares on the fediverse.

Using Facebook souldn't be an official or principal way to communicate for a community around a Free Software (always IMHO)

Forums are good, even if centralized. Should be the official channel.

[ann0see]

Any update on this? Should we also open a pr on the main repo which includes some of this content?

[trebmuh]

I can add this to #127 if we're all good. Are we?

[ann0see]

I would be ok with that. Of course we can still add things to that. But we need to merge it into changes (since we will need to translate it). I'll change the branch.

[ann0see]

Added some more content to this file now.

[ann0see]

Still todo: