Clean up docs-community.readthedocs.io
encukou opened this issue · 5 comments
The docs are a bit of a ghost town. Remove the unnecessary bits, consolidate the necessary ones, and generally make it better.
(But keep in mind it should be living documents: we don't need book-quality prose.)
Yep, I'll take it, can you assign to me?
First batch of questions:
- Who is the audience for these docs? Who isn't the audience? Right now it looks like it's to organize us. But we're using other tools (e.g. here.) Perhaps the audience is outsiders looking to contribute docs plus the PSF key people seeing what we're doing? I presume also this is NOT the place for consumers to ask docs questions.
- Is this intended to be the canonical entry point?
Yep, I'll take it, can you assign to me?
Unfortunartely it's not technically possible to assign you in GitHub UI yet, as you aren't part of the group. I'll hopefully get that sorted around next week.
Consider yourself assigned in the mean time.
outsiders looking to contribute docs
I think it's more for us, the group itself, and for whomever wants to manage docs contributions or read about how higher-level decisions are made.
I also think it should be a place for a style guide, e.g. with the answer from the Avoid addressing the user directly thread. That would be a new section though, we don't have much content for it yet.
But we're using other tools
Right. Docs aren't a good place for discussions, they should have information that's relatively stable.
Links to the discussion spaces should be there, for example.
I presume also this is NOT the place for consumers to ask docs questions.
No, but it would be nice to point them to Discourse.
the PSF key people seeing what we're doing
Anyone seeing what we're doing, if they're interested.