[pytest-dev] pytest documentation

[Daniele Procida]

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