Docs: Let's create a "Common Issues & FAQ" document

[ichard26]

Howdy!

The documentation reorganization effort is in the final stages (see GH-1759 and GH-2174 for details). During the planning stages of the reorganization, I planned for the creation of many more docs. This is one of them.

Summary

Create a document that provides answers to common issues users run into AND to questions often asked. The answers can be self-contained or delegate more detail to another part of the documentation. The requirement for something to join the document is that 1) it would commonly trafficked (or is annoying enough to be worth including) and 2) is user-facing (the contributing section can get its own FAQ or whatever if needed).

Why

During my time as a triager I've noticed issues being opened for the same thing over and over again (e.g. the infamous E203 flake8 lint rule). I've also just noticed user support questions that have a such simple answer that they should be written down somewhere easy to find (e.g. "What's Black's Python support status (especially for Python 2)?").

The main goal is to 1) make it easier for users to quickly get answers to their qualms, and 2) reduce the amount of issue traffic by avoiding duplicates / easily solvable questions / issues.

Contents

• Flake8's infamous E203 (including W503 might not be a bad idea as well)
• Our support policy for Python 2
• "Why is X file not being formatted?" - points to the file collection and discovery docs (probably due to a .gitignore file)
• "Is Black safe to use?" - points to our beta status details and AST policy
• Something about the invalid code error you face with an unterminated fmt: off (Invalid code after indented # fmt: off #569) - not sure how word this one tho
• "Why is this collection not being collapsed" - points to the magic trailing comma docs
• "How stable is Black's style?"
• "Does Black have an API?"

Discussion goals

What else should we include? I'm sure I'm missing a bunch, especially as a newer maintainer of the project :) Also is there anything in my list that we shouldn't include? Finally, what should we write for each Q?

[ichard26]

Hey @felix-hilden I wondering if you'd like to work on this documentation issue. It's a fair bit bigger than what you've worked on previously, but it shouldn't be too difficult for you gauging from your past work (thank you btw!) :)

In terms of what needs to be done for this to progress:

• Define what topics the FAQ should cover - I got a starting list but I'm sure there's more topics we should cover

• Define how each Q will be answered - in particular how much do we want the answers to be self-contained vs lean on other documentation

• Write the docs :)

  For this, I'd personally add another top level page just for this document. I expect it to be pretty high traffic once people learn of its existence and I want to be very discoverable.

cc @cooperlees @JelleZijlstra for their feedback and input here

[felix-hilden]

Actually yeah! As #1746 was closed so abruptly over the weekend I lost what was initially driving me to contribute 😅 But I'd still like for Black to hit stable, so I'm happy to help. And I have a soft spot for documentation too.

That being said, I feel like I'm not the person to ask about the most common issues that users face. I've been watching the repository for a bit though. So putting it together once we figure out the content? Sure thing!

The initial points seem reasonable to me, and I agree that the issue tracker is not the most appropriate place for questions. How should the questions be answered? I like it DRY, sometimes even a bit too much I'll admit. So if it was up to me, I'd always link the relevant docs and avoid any unnecessarily long repetition - unless the topic isn't covered anywhere of course.

[JelleZijlstra]

We could open up GitHub discussion on this repo for questions. I've seen that action on https://github.com/microsoft/pyright and it seems to work well.

[ichard26]

As #1746 was closed so abruptly over the weekend I lost what was initially driving me to contribute

Sorry, sometimes we aren't transparent and open with what us the core team is working on at the moment. This is something I want to see improved (releasing is definitely one example of where more transparency would be lovely). In hidesight, I should've let you know that Łukasz was working on that.

I feel like I'm not the person to ask about the most common issues that users face.

Yeah totally, my intention here was for you to more manage this issue (and then write the docs) collecting feedback from the other maintainers (e.g. Cooper, Jelle, and I!) but it appears it escaped my mind without flowing through my fingers.. 😆 I don't really mind, I'm totally down to help out, it's just that I have other docs I want to write right now (issue triage ATM) so (cause Cooper nudged me to) I was looking for someone to contribute.

We could open up GitHub discussion on this repo for questions.

I'm assuming this is independent of this documentation addition but related. To be clear, even if we do open up GH Discussion, I'd to like to have a FAQ style doc. Although that would definitely help out in the weird more esoteric Qs and user support Qs land.

[felix-hilden]

In hidesight, I should've let you know that Łukasz was working on that.

Much appreciated, and all good! So does this conversation happen on IRC so that others may join as well, or truly only between maintainers?

I'm assuming this [GH Discussions] is independent of this documentation addition but related.

Agreed. I've not really had any experience with Discussions, but it seems to be a good solution to user help flooding the issue tracker. And Pyright has lots of discussion categories, so potentially even more controversial discussions (e.g. style) could be had over there without disturbing the tracker with non-actionable tickets. The voting system would naturally separate the cream from the chaff. But FAQ is still appropriate.

So, two questions stand:

• Are all the items Richard proposed good for the FAQ? If so, we could start by writing them.
• Are there any other items that should be there immediately? Naturally everything can be added later once the document is up.

[ichard26]

Much appreciated, and all good! So does this conversation happen on IRC so that others may join as well, or truly only between maintainers?

Some of it does happen on IRC via the #blackformatter channel on Freenode (well it's only me and Cooper on there), but most of the inter-maintainer communication happens via a private FB Messager group chat.

RE. GH Discussions

👍 to everything said.

Are all the items Richard proposed good for the FAQ? If so, we could start by writing them.

Uh, I CCed a few maintainers to this thread and we have received zero feedback so far so yeah about that... here's a trimmed down list that should be non-controversial:

• Flake8's infamous E203 (including W503 might not be a bad idea as well)
• Our support policy for Python 2
• "Why is X file not being formatted?" - points to the file collection and discovery docs (probably due to a .gitignore file)
• "Is Black safe to use?" - points to our beta status details and AST policy
• "How stable is Black's style?"
• "Does Black have an API?"

Are there any other items that should be there immediately? Naturally everything can be added later once the document is up.

I mean, given that it seems like it's just you and I who are active in this domain and I can't think of anything else to add so 👍.