|
|
Subscribe / Log in / New account

Changing the world with better documentation

Changing the world with better documentation

Posted Jan 29, 2019 15:54 UTC (Tue) by mathstuf (subscriber, #69389)
In reply to: Changing the world with better documentation by nilsmeyer
Parent article: Changing the world with better documentation

> it's a great source of anxiety trying to discern what a whole diverse community of different people might consider "appropriate", "offensive" or "unprofessional".

I don't have that anxiety (well, any more than just making public posts already has). I don't think one needs to proactively think of all ways something might be taken as any of unprofessional, inconsiderate, or offensive. As long as you're receptive to those who say it's a problem (publicly or privately) and respond that you're sorry (at least privately, but a public reply is good as well) and understand that what you've said could have been stated better and that you learn from the experience and improve future behavior I think that you'll be fine. It's always a learning process. I don't have first hand experience for what it's like to experience things from various other views (be it racial, nationality, gender issues, etc.) and I don't have the presumption that I'd be able to figure it out on my own not being part of all groups. But, I can learn from others and from my own mistakes and improve my communication that way.


to post comments

Changing the world with better documentation

Posted Jan 29, 2019 15:57 UTC (Tue) by nilsmeyer (guest, #122604) [Link] (30 responses)

That presumes that the offended party is somehow always right to be offended.

Changing the world with better documentation

Posted Jan 29, 2019 16:09 UTC (Tue) by mathstuf (subscriber, #69389) [Link] (29 responses)

And why wouldn't they? Sure, you can dismiss them as reactionary and difficult, but they may do the same to you.

Changing the world with better documentation

Posted Jan 30, 2019 14:09 UTC (Wed) by codeofdrama (guest, #127444) [Link] (12 responses)

Here's a recent example of an allegation of a violation of no less than two different codes of conduct: Re: [PATCH] lib/scatterlist: Provide a DMA page iterator.
  • To what extend do you think, that the allegation has merrit?
  • What parts of the codes of conducts does the allegation refer to?
  • To what extend do you think, that the language of the allegation itself violates the codes of conduct?
  • Is there proper a place, and way to challenge allegations?
  • Is this an opportunity to improve the Linux kernel code of conduct?

Changing the world with better documentation

Posted Jan 30, 2019 16:20 UTC (Wed) by nix (subscriber, #2304) [Link]

Using offensive hyperbole that the speaker clearly knows to be untrue is probably a bad idea regardless, unless you are trying to cause offence. (I mean, there's no way Christoph doesn't know how much work the AMD folk have put in: their problem is the opposite of laziness, I'm worried they'll be invalided out with crippling RSI).

Changing the world with better documentation

Posted Jan 30, 2019 19:03 UTC (Wed) by mathstuf (subscriber, #69389) [Link]

First, some bullet points:

- I have a few patches in the kernel and maybe a few in fd.o projects, but am not otherwise involved;
- I'm not familiar with the people in the linked thread personally (though I've seen those names and handles on here on occasion);
- I don't know of other behavior that might be related, so I'm looking at this thread in isolation (e.g., does hch have a habit of such reactions or is Daniel Stone trigger happy on invoking the CoC); and
- I'm not familiar with the code in the discussion, so I can't tell if anyone is being purposefully difficult or ignorant as to technical points being made.

> To what extend do you think, that the allegation has merrit?

The thread was civil until the message by hch being called out started implying that the others were lazy rather than disagreeing on technical merits.

> What parts of the codes of conducts does the allegation refer to?

I'd classify it as ad hominem in general. As for CoC references:

Kernel CoC: "Being respectful of differing viewpoints and experiences". There's a technical disagreement of which I can't argue to the merits of, but calling someone lazy is at least not respecting viewpoints. Likely empathy as also slipped a little. fd.o's CoC is largely the same AFAICS.

> To what extend do you think, that the language of the allegation itself violates the codes of conduct?

I assume you're referring to this part:

> if you still can't participate in reasonable discussion like an adult

since I don't see anything remotely at issue with the rest of it. This is not on the same level as the called out behavior, but still not how I think I'd have worded it exactly. The outburst was implying that the others are being lazy for not doing some action. This is a call out to a single instance of behavior being childish (it could have been worded more precisely I think). It's the difference between "that's an asshole thing to do" vs. "you're an asshole". The former (to me; non-native speakers may have different readings) implies that improvement is there by changing one's actions whereas the second is concluding something about the person and that there isn't a(n easy) way to fix something.

I don't know of hch's prior behavior (if any), but in isolation, I probably would have called out the outburst (possibly privately), referencing the CoC, but not "threatening" with it…which is what I see done here. Acknowledgement from hch would be nice to see, but private communication would also likely suffice. I can sympathize with hch on the frustration part, but the right solution is not to imply that other developers are being lazy, but to do as Daniel suggests: take a bit of time to calm down before replying. Maybe better technical details would work, but again, there's obviously some misunderstanding on a technical level here, but it's beyond my personal experience.

> Is there proper a place, and way to challenge allegations?

For reporting behavior, the kernel CoC mentions <conduct@kernel.org> and fd.o mentions 3 email addresses as well as a list. It being private makes it hard to reply to allegations. I don't see evidence that this thread was elevated to an official report (though the callout was from a member of fd.o's conduct team), so I don't know what there is to officially challenge in this instance. But…

> Is this an opportunity to improve the Linux kernel code of conduct?

Absolutely. Every interaction with it is an opportunity to improve it. No different than computer code, law, personal relationships, among many other things in life.

Changing the world with better documentation

Posted Jan 30, 2019 20:17 UTC (Wed) by rgmoore (✭ supporter ✭, #75) [Link] (9 responses)

I think you haven't noticed what's missing from this post: a mention of reporting the comment in question as a violation of the CoC. This is an informal attempt by a peer to bring the conversation back to a more productive tack, with the CoC used as an authoritative reference for what's acceptable. This kind of community enforcement of norms is exactly the way things ought to work; when somebody goes overboard and uses language they shouldn't, the first resort should be other people telling them they're out of line. Formal enforcement should be reserved for cases where that kind of feedback is ineffective.

Changing the world with better documentation

Posted Jan 31, 2019 5:10 UTC (Thu) by neilbrown (subscriber, #359) [Link] (8 responses)

> This is an informal attempt by a peer to bring the conversation back to a more productive tack

It is, but I'd suggest that it is a fairly poor attempt. It comes across, to me, as somewhat heavy-handed and bossy, which isn't very far from the problem with the original.

For reference, the original from Christoph (hch) says:

> That is a bullshit attitude. Just like everyone else makes their
> drivers work you should not be lazy.

which is blunt, terse, crude, and insulting.
(It is also correct - the attitude which Christoph is responding to isn't the sort of attitude we try to encourage in the kernel)
The crudity and insult are certainly unnecessary and best avoided. The bluntness isn't particularly helpful, but that isn't actually a crime.

The response given by Daniel Stone starts:

> Can you not talk to people like that?

This is poorly constructed. Christoph certainly can "not talk to people like that", but he chooses otherwise. I know what Daniel means, but his meaning is different to what the words say. Ambiguity is always best avoided, most particularly when there is disagreement.
I would suggest something like:

> Please don't talk to people like that.

or even

> I agree in principal, but think the message would be clearer if stated more politely.

or any number of options are that polite, unambiguous, and (ideally) helpful.

He continues:

> I have absolutely no idea how you can look at the work the AMD people have put in over many years and conclude that they're 'lazy'.

This seems to me to be a misunderstanding. Christoph is not accusing the whole team of laziness over an extended period. He is accusing a specific developer (possibly extending to an immediate team) of a single instance of laziness.
The driver (according to Christoph) should be written to work on architectures which don't support coherent dma mapping in general - it shouldn't fail to load if the require mapping semantics aren't available.

When someone has behaved poorly, accusing them of a much larger offense is a common tactic, but not a wise or helpful one. I don't know that it was deliberate on Daniel's part in this case, but it certainly weakens his case.

Daniel continues (I skip various bits):

> and if you still can't participate in reasonable discussion like an adult

Here Daniel effectively accuses Christoph of acting like a child, which seems to me to be roughly on par with Christoph accusing others of being lazy. When trying to help someone correct their behavior, it is not wise to emulate that behavior in the process.

If I were in Christoph's position, I would have little difficulty shrugging this off as an ignorant response - which is unfortunate because I think Daniel was right to respond and should be commended and encouraged.

I would recommend:
- be emphatically polite - show that it can be done, and show how.
- be specific. Make sure you understand what is said, focus on the specific problem, explain how that comes across poorly, and point the the specific section of any CoC that you feel has been violated (if you want to bring the CoC up at all).

Changing the world with better documentation

Posted Jan 31, 2019 11:51 UTC (Thu) by nilsmeyer (guest, #122604) [Link] (7 responses)

> If I were in Christoph's position, I would have little difficulty shrugging this off as an ignorant response - which is unfortunate because I think Daniel was right to respond and should be commended and encouraged.

This seems to be the only instance of Daniel participating in the thread, I think it's also poor form to step in on someone else's behalf without giving Christian time to respond.

Changing the world with better documentation

Posted Jan 31, 2019 19:52 UTC (Thu) by jani (subscriber, #74547) [Link] (6 responses)

> This seems to be the only instance of Daniel participating in the thread,
> I think it's also poor form to step in on someone else's behalf without
> giving Christian time to respond.

On the contrary, I think it's far better for people who are outsiders in the argument at hand but established members of the community to speak up. The graphics community and dri-devel are fairly civil, and I'd pretty much expect someone to speak up and not let it slide.

Indeed, per the freedesktop.org CoC, maintainers are on the hook for enforcing, which is the main difference to the kernel CoC. See c1d1ba844f01 ("Code of conduct: Fix wording around maintainers enforcing the code of conduct").

Changing the world with better documentation

Posted Feb 1, 2019 4:05 UTC (Fri) by nilsmeyer (guest, #122604) [Link] (5 responses)

>On the contrary, I think it's far better for people who are outsiders in the argument at hand but established members of the community to speak up. The graphics community and dri-devel are fairly civil, and I'd pretty much expect someone to speak up and not let it slide.

I have to respectfully disagree there. It may be a cultural thing, but I find it extremely rude to take offense on someone else's behalf. It suggests that person or group can't speak up for themselves and robs them of agency. I don't know if Christian asked Daniel to defend him.

Changing the world with better documentation

Posted Feb 1, 2019 14:46 UTC (Fri) by jani (subscriber, #74547) [Link]

> I have to respectfully disagree there. It may be a cultural thing, but I find it extremely
> rude to take offense on someone else's behalf. It suggests that person or group can't
> speak up for themselves and robs them of agency.

I can sympathize with that view. However, my point is, it's not just about anyone taking offense or speaking up to defend themselves to begin with. It's also about making clear to *everyone* what's not okay, regardless of what the people involved think. I think it's a much stronger message to and about the community. It's also why I prefer public replies asking people to behave themselves. The mailing list archives will record the standard we've walked past.

Changing the world with better documentation

Posted Feb 2, 2019 13:19 UTC (Sat) by emorrp1 (guest, #99512) [Link] (3 responses)

> It suggests that person or group can't speak up for themselves

Indeed, I'm hoping one of mid-term societal outcomes of this kind of conflict is an increase in personal resilience (shrug it off as another commenter put it). However, I also saved this link to remind myself of why someone may be hesitant to stand up for themselves: https://lists.debian.org/debian-devel/2018/07/msg00364.html

Changing the world with better documentation

Posted Feb 4, 2019 10:12 UTC (Mon) by nilsmeyer (guest, #122604) [Link] (2 responses)

Interesting link, I've been watching that case with interest. I don't think the word boob is offensive, neither is the body part, what I find problematic though is that this seems like a an attempt at trolling. I think the problem here really is that the men don't want to touch that problem either. No one really wants to deal with the kind of shitstorm it's gonna entail, and naturally the 4chan crowd will single out the person they consider the most vulnerable. Personal resilience is one thing when it's just two people communicating in good faith, it's an entirely different beast if you have bad faith actors in play. Even worse, there seems to be no real defense against these types of attacks. Online death threats, stalking and harassment are often entirely ignored by police, and it can be very hard to do anything against actors from different countries.

Changing the world with better documentation

Posted Feb 4, 2019 22:47 UTC (Mon) by emorrp1 (guest, #99512) [Link] (1 responses)

At risk of going off-topic but the framing of this comment makes sense to me: https://lists.debian.org/debian-devel/2018/07/msg00428.html Though I understand the sexism/censorship angle just drew more attention, I believe the maintainer was more convinced by the upstream's hostility to removing unnecessary, potential (depending on jurisdiction) hate-speech source code comments - the software itself was just not so fundamentally unique/useful enough to overcome the attitude/fork it, so I wouldn't say it was censored.

Changing the world with better documentation

Posted Feb 7, 2019 8:14 UTC (Thu) by nilsmeyer (guest, #122604) [Link]

I think upstream is trying to bait / troll people into having that exact debate. I would focus on that. I don't care in particular about "objectification", though the overuse of sex in advertising is annoying (as is advertising in general).

Changing the world with better documentation

Posted Jan 30, 2019 23:31 UTC (Wed) by nilsmeyer (guest, #122604) [Link] (2 responses)

> And why wouldn't they? Sure, you can dismiss them as reactionary and difficult, but they may do the same to you.

and how do you resolve this conflict? Let's say someone objects to the term "master" (like master branch) on the grounds of being offended by it.

Changing the world with better documentation

Posted Jan 30, 2019 23:52 UTC (Wed) by mjg59 (subscriber, #23239) [Link] (1 responses)

> and how do you resolve this conflict?

You have a reasonable conversation, attempt to understand the perspective of the other point of view, make a decision and then follow through on it. You're not necessarily going to find a solution that makes everyone happy, but that's not a reason not to try.

Changing the world with better documentation

Posted Jan 31, 2019 3:47 UTC (Thu) by nilsmeyer (guest, #122604) [Link]

> You have a reasonable conversation, attempt to understand the perspective of the other point of view, make a decision and then follow through on it. You're not necessarily going to find a solution that makes everyone happy, but that's not a reason not to try.

reasonable is another very ambiguous term. Also, when my goal is to develop good software, how is that helped by having debates like that?

Changing the world with better documentation

Posted Feb 1, 2019 4:10 UTC (Fri) by nilsmeyer (guest, #122604) [Link] (12 responses)

Another argumentum ad absurdum: We personally identify as the reincarnation of Napoléon Bonaparte I, by god's grace, legitimate emperor of all of Europe and Tsar of all Russias. You are to refer to me as "Your Majesty", and use the pluralis maiestatis in all communication. I will take great offence if you fail to do so.

To what extent are you required to participate in my delusion?

Changing the world with better documentation

Posted Feb 1, 2019 5:28 UTC (Fri) by mjg59 (subscriber, #23239) [Link] (11 responses)

Do you honestly and earnestly identify that way?

Changing the world with better documentation

Posted Feb 1, 2019 6:36 UTC (Fri) by nilsmeyer (guest, #122604) [Link] (4 responses)

How dare you question that?

Changing the world with better documentation

Posted Feb 1, 2019 7:55 UTC (Fri) by mjg59 (subscriber, #23239) [Link] (3 responses)

Ok cool so you're actually just joking about people who don't fall into the male/female binary spectrum and minimising the distress caused by inappropriate pronoun usage rather than trying to engage in any sort of reasonable conversation.

Changing the world with better documentation

Posted Feb 1, 2019 12:34 UTC (Fri) by nilsmeyer (guest, #122604) [Link] (2 responses)

Of course its a joke but it's a setup for a larger point. I am minimizing the distress that wrong pronouns (malice aside) cause. If this is causing someone severe distress that's a sign of a deeper issue (trauma for example).

The binary spectrum is somewhat of a crutch but it works for the majority of people. Of course there are more sexes than male / female but as an approximation this can work. Just pick one, or none.

I don't have a problem when someone wants to be addressed with different male / female pronouns, and I can tolerate they / them, but don't call me an asshole when I don't get it right the first time. It's a matter of politeness I believe. I draw the line at Ze/Hir or some other recently made up pronouns. Trying to stay abreast of all the identities and pronouns that people came up with is almost a full time job, and basically it's asking me to agree fully with a political opinion or a philosophy (gender as a social construct). That's quite an imposition. There are even cases where someone tried to remove / discipline a developer on CoC grounds for voicing their opinion in other channels.

You can't be welcoming to everyone, very often to me it seems that CoC are designed to exclude the conservative and perhaps people on the autism spectrum. I think of course you are allowed to do that if you want to. If that's the goal, I would like it to be stated in the open instead of clouded in language of inclusiveness. Many times though it seems these things are backdoored into projects.

Apparently there are even people who identify as a different species, a fictional species or an object. It's impossible to tell if I'm being trolled. Very often this seems more like a lifestyle choice, to make yourself look more interesting, which I believe belittles the struggle of people with actual gender identity problems. Of course whether someone identifies as an Apache Helicopter doesn't really factor in to communication.

I had a classmate who later had gender reassignment surgery. What impressed me very much about her was the fortitude she displayed when dealing with abuse from others, which was sadly extremely frequent in that part of town (many conservative Muslims).

As a matter of practicality, does this extreme inclusiveness actually cause an influx of talent?

Changing the world with better documentation

Posted Feb 1, 2019 13:21 UTC (Fri) by james (subscriber, #1325) [Link] (1 responses)

If this is causing someone severe distress that's a sign of a deeper issue (trauma for example).
Possibly. I'd hope most people would want to respect that distress, and not expect sufferers to shun human contact until the underlying issues were addressed.

There is a certain amount of help that tooling can bring: I used to configure mutt to display emails from certain senders in a different colour, with one key to add someone to the list.

I used it to identify people who had their own viewpoints which were best respected from a distance, shall we say, but it would be easy to set up another list of people who needed extra care.

Changing the world with better documentation

Posted Feb 2, 2019 20:15 UTC (Sat) by nilsmeyer (guest, #122604) [Link]

I don’t really think a free software project with communication channels open to everyone is necessary a healthy place if you suffer these kinds of issues, the larger internet certainly isn’t.

Your technological solutions is an interesting idea.

Changing the world with better documentation

Posted Feb 1, 2019 11:19 UTC (Fri) by lkundrak (subscriber, #43452) [Link] (5 responses)

If they indeed do, then I suppose Their Majesty has some explaining to do in front of the international criminal court on the matters of war crimes.

More seriously though, can the question of anyone's internal honesty on these matters be reliably answered? Does it even matter at all?

I man, if there's no cost associated with following whichever rules the other party finds respectful, why not just follow them? I guess we'll all be better off that way, including people that are distressed by being addressed with a different pronoun than they prefer, those who don't care, as well as Their Majesty.

Changing the world with better documentation

Posted Feb 2, 2019 13:35 UTC (Sat) by emorrp1 (guest, #99512) [Link] (3 responses)

The problem is that there *is* a cost to this imposition of a particular communication style.

It used to be "professional" in documentation, journalism style guides etc. to refer to a person of unknown (but binary) gender as "he". I consider it right that this is hopefully now replaced with a more neutral "they", especially with an anonymous internet - but even making that habitual change is difficult for many.

So I'd say expecting others to use even more specific, unfamiliar pronouns, on a per-individual basis is going too far. Probably best experienced by interacting with kids just learning to talk "look, man with beard" is not easily replaced with "look, person with beard" - assuming the interesting thing about them from kids' point of view was an unfamiliar beard.

Changing the world with better documentation

Posted Feb 2, 2019 16:58 UTC (Sat) by jani (subscriber, #74547) [Link]

Here's another angle to this. There are gender neutral languages. My native tongue, Finnish, has only gender neutral pronouns and completely lacks grammatical gender.

Getting the gender pronouns and grammatical gender right in foreign languages can be incredibly hard. It's a fairly common mistake for Finns to get them wrong. I can relate to the difficulty of learning new pronouns. From experience, I think gender neutral pronouns are superior.

Changing the world with better documentation

Posted Feb 4, 2019 3:30 UTC (Mon) by flussence (guest, #85566) [Link] (1 responses)

I agree with this. The cost is real (and there's probably something on sci-hub that quantifies exactly what it is); the average human brain has about as many free registers as an i686 and its task switches are slow and prone to data loss. In the context of trying to communicate technical ideas without being interrupted by off-topic nitpicking, I think *gradually* refactoring language toward terms like “they” is fine.

Changing the world with better documentation

Posted Feb 4, 2019 15:59 UTC (Mon) by nilsmeyer (guest, #122604) [Link]

Or we could all start learning Finnish. It's probably possible in documentation to use more neutral language, or switch up gendered pronouns (or even develop a way to automatically convert it into the form preferred by the reader), this is a lot harder to do with they since they usually means a group of people, so you lose precision immediately. Does this make documentation better? I think it's harder to understand, and even harder to write that way, especially if you don't have that much experience in the English language. There is a cost to everything.

Alice and Bob (and so forth) are often used as examples in documentation.

Changing the world with better documentation

Posted Feb 2, 2019 20:10 UTC (Sat) by nilsmeyer (guest, #122604) [Link]

It’s „Your imperial Majesty“. I got the styles a bit wrong ;)

There is a cost associated I believe. First of all you now have to remember how to refer to a certain person, there’s a need to educate new people so as not to upset anyone and inevitably not everyone will accept it, causing further conflict. It’s a question of whether you want to include people who make communication extremely difficult and what their potential contributions are.

Changing the world with better documentation

Posted Jan 30, 2019 15:50 UTC (Wed) by nix (subscriber, #2304) [Link] (3 responses)

Well that entirely depends on what 'unprofessional' is taken to mean. I've had past bosses who've insisted vociferously that admitting that your own software contains any bugs whatsoever is the epitome of 'unprofessional', even to long-term clients who have reported thousands of them, even when talking about one of those bugs. (One boss said that everything was suddenly OK if you called them 'issues' instead, which is the sort of meaningless ritual word transformation that is surely only going to fool an utter moron and is unlikely to lead to changing levels of offence or legal risk since 'bug' is not an expletive or emotionally-loaded term: the other boss wanted me to never discuss bugs at all unless they were already fixed, which made it very hard to collect enough information to fix them.)

I operate by the rule of simply trying to treat people decently: I'm not going to try to waste time figuring out what level of legal paranoia the sort of people who use the word 'unprofessional' happen to mean this week.

Changing the world with better documentation

Posted Jan 30, 2019 19:43 UTC (Wed) by mathstuf (subscriber, #69389) [Link] (1 responses)

> <bug paranoia>

Yeah…I'd have personally started looking elsewhere for employment. I don't see that being any different of a situation than having irreconcilable differences in a personal relationship and cutting it off. Granted, alternative employment opportunities generally being more necessary than having an SO of some kind may make it hard to have a gap.

> the other boss wanted me to never discuss bugs at all unless they were already fixed

Other companies go even farther and don't discuss unless a fix has been released. Again, not somewhere I'd want to work. Luckily, I get to work on FOSS even at my employer where the issue tracker is public.

> I operate by the rule of simply trying to treat people decently: I'm not going to try to waste time figuring out what level of legal paranoia the sort of people who use the word 'unprofessional' happen to mean this week.

I agree with this. However, when informed of some behavior stepping over a line, it is best to take that into account for future interactions.

Changing the world with better documentation

Posted Jan 30, 2019 21:37 UTC (Wed) by nix (subscriber, #2304) [Link]

> Yeah…I'd have personally started looking elsewhere for employment

I did! Eventually. I had this feeling that doing free software hacking for pay would take all the fun out of it, y'see... (in a twist unsurprising to anyone here, it didn't. Having really clued co-workers is a big part of that.)

Changing the world with better documentation

Posted Jan 31, 2019 20:07 UTC (Thu) by epa (subscriber, #39769) [Link]

A level up from 'issues' is to call them 'challenges'...


Copyright © 2025, Eklektix, Inc.
Comments and public postings are copyrighted by their creators.
Linux is a registered trademark of Linus Torvalds