From daniele at vurt.org  Sat Feb 27 07:25:40 2021
From: daniele at vurt.org (Daniele Procida)
Date: Sat, 27 Feb 2021 12:25:40 +0000
Subject: [pytest-dev] pytest documentation
In-Reply-To: <CA+RQFffsmLST2VkuFamCQwF2NjZYijQRn3JDUS-KdMc+PDeLRg@mail.gmail.com>
References: <CA+RQFffsmLST2VkuFamCQwF2NjZYijQRn3JDUS-KdMc+PDeLRg@mail.gmail.com>
Message-ID: <20210227122540.43030039@mail.gandi.net>

Hello pytest developers.

As you may remember, back in 2017 at EuroPython in Rimini I made an attempt to restructure pytest's documentation, according to the principles in https://documentation.divio.com. See https://github.com/pytest-dev/pytest/issues/4119 and <https://github.com/pytest-dev/pytest/compare/master...evildmp:documentation-restructure>.

It wasn't a success, and that was because I tried to do too much at once when too much else was going on at the same time.

I'd like to have another attempt, but to approach it in a different way that has worked well for me since then. 

Rather than work on a large, monolithic reorganisation as I tried before, I would like to do it in very small commits and cycles, that can quickly be checked, approved and merged, over a period of a few weeks.

Would you be interested in my tackling this again? I believe that this approach will be successful in a way that it wasn't last time.

To help make it work, I would need to be able to rely on very short review/merge cycles, which I know is asking a lot in a project like this. On the other hand, each proposed change will typically be very small and easy to review. In fact some of them will likely seem quite trivial or banal in content, but if you can put up with that during the process, it's part of the approach.

I will use the work as an example for my talk in April at Write the Docs, https://www.writethedocs.org/conf/portland/2021/speakers/#speaker-daniele-procida, so that also gives you an idea of when I expect the process to be largely complete (I will also discuss my original attempt, and why it failed).

I understand if you feel that this would require too much effort from the team to be worthwhile, but if you think it could be a good idea, I'd be happy to outline what I have in mind in more detail.

Thanks a lot,

Daniele


From nicoddemus at gmail.com  Sat Feb 27 08:51:49 2021
From: nicoddemus at gmail.com (Bruno Oliveira)
Date: Sat, 27 Feb 2021 10:51:49 -0300
Subject: [pytest-dev] pytest documentation
In-Reply-To: <20210227122540.43030039@mail.gandi.net>
References: <CA+RQFffsmLST2VkuFamCQwF2NjZYijQRn3JDUS-KdMc+PDeLRg@mail.gmail.com>
 <20210227122540.43030039@mail.gandi.net>
Message-ID: <CA+RQFfd11HSr6a1Pfrs3JwNE3X=xqzwxth+6LQ4WAnU0LQYJ2g@mail.gmail.com>

Hi Daniele,

On Sat, Feb 27, 2021 at 9:26 AM Daniele Procida <daniele at vurt.org> wrote:

> As you may remember, back in 2017 at EuroPython in Rimini I made an
> attempt to restructure pytest's documentation, according to the principles
> in https://documentation.divio.com. See
> https://github.com/pytest-dev/pytest/issues/4119 and <
> https://github.com/pytest-dev/pytest/compare/master...evildmp:documentation-restructure
> >.
>
> It wasn't a success, and that was because I tried to do too much at once
> when too much else was going on at the same time.
>

Understandable, it is hard to apply large changes over a long period of
time, especially documentation which has small additions/changes all the
time, which causes conflicts in the long term. Also, life happens.

I'd like to have another attempt, but to approach it in a different way
> that has worked well for me since then.
>
> Rather than work on a large, monolithic reorganisation as I tried before,
> I would like to do it in very small commits and cycles, that can quickly be
> checked, approved and merged, over a period of a few weeks.
>

That sounds good to me.

Are the small changes self-contained? If so, I think they can target the
master branch as usual with other PRs.

If however the changes are just part of an overall redesign, where it only
makes sense to publish them to users once the overall redesign is complete,
we can have a separate branch in the repository, like before.

Would you be interested in my tackling this again? I believe that this
> approach will be successful in a way that it wasn't last time.
>

>From my part, definitely. I really liked the direction that redesign was
going.

To help make it work, I would need to be able to rely on very short
> review/merge cycles, which I know is asking a lot in a project like this.
> On the other hand, each proposed change will typically be very small and
> easy to review. In fact some of them will likely seem quite trivial or
> banal in content, but if you can put up with that during the process, it's
> part of the approach.
>

Overall our review response is quick, usually within 1-2 days (if not a few
hours). What do you think would be required for this work?

I will use the work as an example for my talk in April at Write the Docs,
> https://www.writethedocs.org/conf/portland/2021/speakers/#speaker-daniele-procida,
> so that also gives you an idea of when I expect the process to be largely
> complete (I will also discuss my original attempt, and why it failed).
>
> I understand if you feel that this would require too much effort from the
> team to be worthwhile, but if you think it could be a good idea, I'd be
> happy to outline what I have in mind in more detail.
>

I definitely think it would be a good idea, but I'm interested to hear what
the other maintainers think as well.

Thanks for offering to contribute again!

Cheers,
Bruno.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.python.org/pipermail/pytest-dev/attachments/20210227/53357b59/attachment.html>

From daniele at vurt.org  Sat Feb 27 13:13:27 2021
From: daniele at vurt.org (Daniele Procida)
Date: Sat, 27 Feb 2021 18:13:27 +0000
Subject: [pytest-dev] pytest documentation
In-Reply-To: <CA+RQFfd11HSr6a1Pfrs3JwNE3X=xqzwxth+6LQ4WAnU0LQYJ2g@mail.gmail.com>
References: <CA+RQFffsmLST2VkuFamCQwF2NjZYijQRn3JDUS-KdMc+PDeLRg@mail.gmail.com>
 <20210227122540.43030039@mail.gandi.net>
 <CA+RQFfd11HSr6a1Pfrs3JwNE3X=xqzwxth+6LQ4WAnU0LQYJ2g@mail.gmail.com>
Message-ID: <20210227181327.1035102291@mail.gandi.net>

Bruno Oliveira wrote:

>> Rather than work on a large, monolithic reorganisation as I tried before,
>> I would like to do it in very small commits and cycles, that can quickly be
>> checked, approved and merged, over a period of a few weeks.

>Are the small changes self-contained? If so, I think they can target the
>master branch as usual with other PRs.
>
>If however the changes are just part of an overall redesign, where it only
>makes sense to publish them to users once the overall redesign is complete,
>we can have a separate branch in the repository, like before.

That's exactly the thing I want to and think I can successfully avoid. The changes will be iterative and evolutionary. The idea is that each one will contain something - however small - that moves in the right direction and can be included. 

So yes, I would like to target the master branch, in effect with a stream of small commits. It's possible to do this with documentation in a way that's not possible with code.

>>To help make it work, I would need to be able to rely on very short
>> review/merge cycles, which I know is asking a lot in a project like this.
>> On the other hand, each proposed change will typically be very small and
>> easy to review. In fact some of them will likely seem quite trivial or
>> banal in content, but if you can put up with that during the process, it's
>> part of the approach.

>Overall our review response is quick, usually within 1-2 days (if not a few
>hours). What do you think would be required for this work?

That would certainly work for me. 

>Thanks for offering to contribute again!

I'd really like to do this, it has been on my mind since 2017!

But as it could be annoying for the team to be faced with the proposed stream of very small commits, I'd like to get a sense whether it would fit with the way you actually want to work.

Regards,

Daniele