Context is important: documentation is not the same as code

[sebb <se...@gmail.com>]

The CLC tool currently considers all source files to be equal.

However in terms of the effect on readers, documentation (e.g.
website, user guides) is far more likely to cause upset.

This is mainly because it has a wider readership.

Also people reading code will likely understand that words are
generally being used in their technical sense. And they may also
appreciate that it can be a lot harder to change such words.

Sebb

Re: Context is important: documentation is not the same as code

[sebb <se...@gmail.com>]

On Sat, 4 Sept 2021 at 19:30, Rich Bowen <rb...@rcbowen.com> wrote:
>
> On Sat, Sep 4, 2021, 10:44 sebb <se...@gmail.com> wrote:
>
> > On Sat, 4 Sept 2021 at 14:16, Rich Bowen <rb...@rcbowen.com> wrote:
> > >
> > > While this is absolutely true, our mandate is to grow developer
> > communities
> > > and the diversity thereof. As such it is that audience - the
> > code-readers -
> > > which we are primarily concerned with, right?
> > >
> >
> > Is the remit of D&I that narrow?
> >
> > What about readers of the ASF websites and users of ASF software?
> >
> > Besides, a potential developer probably starts by reading about some
> > ASF software, and studies the user docs before wanting to engage as a
> > developer.
> >
>
> Sure. I don't disagree with you.

Glad to hear it.

> So what are you suggesting we do differently here, specifically?

The analysis output needs to show whether word matches appear in code
or elsewhere, and offer the option to suppress code matches.

This is because matches in code are likely to be much harder to fix,
as well as having less visibility in general.

At the moment every match is treated as being of equal importance,
when that is clearly not the case.

We should be making it easier for projects to fix unnecessary usages
of problematic language, so showing all possible matches from the
start is not helpful.
It should be possible to start with the most likely problematic
instances and gradually expand the search.

Sebb.

Re: Context is important: documentation is not the same as code

[Rich Bowen <rb...@rcbowen.com>]

On Sat, Sep 4, 2021, 10:44 sebb <se...@gmail.com> wrote:

> On Sat, 4 Sept 2021 at 14:16, Rich Bowen <rb...@rcbowen.com> wrote:
> >
> > While this is absolutely true, our mandate is to grow developer
> communities
> > and the diversity thereof. As such it is that audience - the
> code-readers -
> > which we are primarily concerned with, right?
> >
>
> Is the remit of D&I that narrow?
>
> What about readers of the ASF websites and users of ASF software?
>
> Besides, a potential developer probably starts by reading about some
> ASF software, and studies the user docs before wanting to engage as a
> developer.
>

Sure. I don't disagree with you.  So what are you suggesting we do
differently here, specifically?

Re: Context is important: documentation is not the same as code

[sebb <se...@gmail.com>]

On Sat, 4 Sept 2021 at 14:16, Rich Bowen <rb...@rcbowen.com> wrote:
>
> While this is absolutely true, our mandate is to grow developer communities
> and the diversity thereof. As such it is that audience - the code-readers -
> which we are primarily concerned with, right?
>

Is the remit of D&I that narrow?

What about readers of the ASF websites and users of ASF software?

Besides, a potential developer probably starts by reading about some
ASF software, and studies the user docs before wanting to engage as a
developer.

> Shosholoza,
> Rich
>
>
> On Sat, Sep 4, 2021, 07:25 sebb <se...@gmail.com> wrote:
>
> > The CLC tool currently considers all source files to be equal.
> >
> > However in terms of the effect on readers, documentation (e.g.
> > website, user guides) is far more likely to cause upset.
> >
> > This is mainly because it has a wider readership.
> >
> > Also people reading code will likely understand that words are
> > generally being used in their technical sense. And they may also
> > appreciate that it can be a lot harder to change such words.
> >
> > Sebb
> >

Re: Context is important: documentation is not the same as code

[Rich Bowen <rb...@rcbowen.com>]

I suppose my question here is… ok assuming that is true, what are you
suggesting we do about it?

Shosholoza,
Rich


On Sat, Sep 4, 2021, 09:16 Rich Bowen <rb...@rcbowen.com> wrote:

> While this is absolutely true, our mandate is to grow developer
> communities and the diversity thereof. As such it is that audience - the
> code-readers - which we are primarily concerned with, right?
>
> Shosholoza,
> Rich
>
>
> On Sat, Sep 4, 2021, 07:25 sebb <se...@gmail.com> wrote:
>
>> The CLC tool currently considers all source files to be equal.
>>
>> However in terms of the effect on readers, documentation (e.g.
>> website, user guides) is far more likely to cause upset.
>>
>> This is mainly because it has a wider readership.
>>
>> Also people reading code will likely understand that words are
>> generally being used in their technical sense. And they may also
>> appreciate that it can be a lot harder to change such words.
>>
>> Sebb
>>
>

Re: Context is important: documentation is not the same as code

[Rich Bowen <rb...@rcbowen.com>]

While this is absolutely true, our mandate is to grow developer communities
and the diversity thereof. As such it is that audience - the code-readers -
which we are primarily concerned with, right?

Shosholoza,
Rich


On Sat, Sep 4, 2021, 07:25 sebb <se...@gmail.com> wrote:

> The CLC tool currently considers all source files to be equal.
>
> However in terms of the effect on readers, documentation (e.g.
> website, user guides) is far more likely to cause upset.
>
> This is mainly because it has a wider readership.
>
> Also people reading code will likely understand that words are
> generally being used in their technical sense. And they may also
> appreciate that it can be a lot harder to change such words.
>
> Sebb
>