regarding the topic Code of Conduct: it’s probably better to link to https://github.com/RIOT-OS/RIOT/blob/master/CODE_OF_CONDUCT.md instead of copying the content of this file. otherwise, we have multiple sources to maintain – we learned from the GitHub wiki usage that this is not a good idea.
(sorry for posting in a separate topic but the other i locked.)
[kaspar@ng riot (master)]$ git log CODE_OF_CONDUCT.md
commit 628c97c0792bec001be86ffa072d715a199b884a (miri64/github/enh/code-of-conduct)
Author: Martine Lenders <m.lenders@fu-berlin.de>
Date: Wed Nov 22 16:56:34 2017 +0100
github: add Code of Conduct
[kaspar@ng riot (master)]$
Maybe implement this idea when we touch this the next time?
i would do it right away. we will just forget it otherwise.
cheers matthias
I copied it over because the CoC almost never changes (no changes so far as shown by @Kaspar). It saves the user a click.
To prevent issues when they do start to diverge, which I would consider very unlikely, I added a note at the bottom stating that the version on GitHub is leading with a link to our CoC on GitHub.
as i wrote: we had this experience in the past with the wiki pages. we then consolidated content. why do we don’t learn from the past?
I don’t see how this compares with the wiki situation we had. A huge difference with the wiki pages and the board docs inside the RIOT tree is that they got modified often, making it high effort to keep them in sync.
We’re not dealing here with a document that is modified often, but which is (or should be) opened often, preferably at least once by every new user on the forum.
I don¢t see how this compares with the wiki situation we had. A huge difference with the wiki pages and the board docs inside the RIOT tree is that they got modified often, making it high effort to keep them in sync.
i was not only referring to the board docs but also to CONTRIBUTING.md, CODING_CONVENTIONS… etc.
We¢re not dealing here with a document that is modified often, but which is (or should be) opened often, preferably at least once by every new user on the forum.
i cannot follow the argumentation. how often a document is changed or how often the document is read doesn’t have an impact on solving incosistent content upfront.
cheers matthias
there is an on-going discussion about a sync feature in Discourse here: https://meta.discourse.org/t/embedding-external-markdown/118601
That should be simple. If a document never changes, multiple copies cannot get out of sync.
we had an agreement that it might change in the future…
We need to start having a place where all our agreements are collected. I’m getting confused.
The point here is that this specific document did not change a single time in the last three years. It is customary that a forum places its code of conduct prominently and easy to reach, that’s why it is nicer to have it inline and not hidden behind a link. It does matter if it is more often read than changed, if there’s a huge difference and we want to save new users from doing the extra click.
i argue that it is very important that the RIOT Code of Conduct is consistent.
the authorative source is
in the Discourse topic, Koen added a link to the repo. as you both argued a user will never click on this link. as such, in the worst case, the user will end with outdated information.
you could add a warning “if you change, please update …” upfront in the CODE_OF_CONDUCT.md but this seems very ugly to me.
cheers matthias
I don’t really get why this is important to you @Kaspar and @bergzand. I strongly agree with Matthias, having it in two places is not much better than code duplication, which was criticized more than once before.
Having it one link/click away, publicly available should not be a burden nowadays.
As long as there is no automated way to copy paste possible changes, we shouldn’t keep this document in two places.
OT:
We need to start having a place where all our agreements are collected. I’m getting confused.
That seems kinda like a good idea.
Sorry folks, I don’t really understand the point of the discussion: I understood that Discourse cannot embed content from other sources. Correct? So the decision is whether we can expect a visitor to take an additional click to read the document or maintain a copy of a (mostly) static document?
yes. and whether we want to take a worst-case risk, i.e., outdated document.
Isn’t the debate actually on what the worst case risk really is here?
(most?) people not reading the Code of Conduct
some people (temporarily?) exposed to a document which (very slightly?) differs from our actual Code of Conduct
Yes, the way I see this it is an user experience issue. In the end, it is advantageous to us to have our visitors here read the CoC. Most of the time they won’t be looking for it or won’t need it, but we still want them to read it because we need them to be aware of the rules here. Adding another click to a process we try to get a visitor to complete just lowers the number of people actually reading the document.
Maybe I’m wrong on this, but I don’t think we’ll suddenly have a full rewrite of the document, at most some tuning to emphasize different aspects or extend the list of spaces. So this worst case risk has in my opinion negligible consequences.
Would it improve the situation for you if we put the link to the CoC on top of the post and refer to the copy as a copy?
yes. and whether we want to take a worst-case risk, i.e., outdated document.
so what happens if this specific document is outdated? Instead of not accepting descrimination, we now suddenly do? Probably not. Painting inconsistency in this as worst case makes the worst case not so bad. Any change would not substantially change this document.
Having it inline would at least make a change visible to users that have already read it, as discourse would mark it as new or changed. If it is a link and we don’t “touch” the topic, noone not involved in the PR’s changing the document would realize. So changes to the CoC should lead to manual action here anyways, otherwise we have consistensy but not visibility, leading to inconsistency where it matters, at the last level: in our heads.
Does a link make user’s not read the document? Surely not 100% will click on the topic. Of those, not 100% will neither read nor click a link. Whether a link will make less users read the CoC is speculation, but I think we can make an educated guess on that.
Anyhow, I’m out, I realize I don’t care.
This should be an acceptable compromise.