You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
"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?
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
fmt: off(Invalid code after indented# fmt: off#569) - not sure how word this one thoDiscussion 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?