If we were to apply for Google Season of Docs, what would be the areas that we might want to invest that technical writing expertise?
Let’s aggregate a list of such cases here, so that we have something to use if we do apply for GSoD, or some other funding to hire technical writers.
I’m guessing this would be purely toward improving the tutorials on packaging.python.org, but this would definitely be great to have.
I imagine Maintainer feedback required for user research would also surface some areas in pip’s documentation, and likely some other parts of the ecosystem as well.
The setuptools documentation is in dire need of a total revamp. I think that @jaraco has been working with someone (alvyjudy on github) on refactoring the setuptools documentation — here is a preview link — but I think the whole build machinery is terribly under-documented, even if you include the distutils documentation.
Even with the new revamp (which I’ve only skimmed over), I could still imagine setuptools as being the best bang for the buck in terms of technical writing.
For reference - we are carrying out UX research to help identify how we can improve pip’s documentation:
We plan on making recommendations after our research is complete.
The scope here is pip specific, but I can imagine that many of our findings might be applicable to the wider packaging ecosystem.
The accepted projects have now been announced
https://developers.google.com/season-of-docs/docs/participants/ in case
they help people think of good projects for next time.
Executable test cases (e.g. Python and/or Shell scripts) might be most helpful.
Could there be a CLI flag that helps pip generate test cases?
A template for [new resolver] test case functions would be easy for a maintainer to create (and maybe add to the CLI and preliminary documentation)