Hi Daniele, On Sat, Feb 27, 2021 at 9:26 AM Daniele Procida <dani...@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.
_______________________________________________ pytest-dev mailing list pytest-dev@python.org https://mail.python.org/mailman/listinfo/pytest-dev
