Add guidelines for formatting questions and explanations
- Dominant language
- Python
- Stars
- 129
- Forks
- 15
- PR merge metrics
- No merged PRs in 30d
Description
Suggestions from @tocic:
\ — \ — \:
1. use ``` instead of ` ` for code blocks (even inside quotes) — easier to read/write, code highlighting — greppable
2. no `using namespace std;` — more vertical space — `clang-tidy`/greppable
3. no EOL at EOF — consistency — `clang-format` can consistently do the opposite
4. 2 or 4 spaces for code indentation — consistency, more horizontal space — `clang-format`
5. `(...)` for omitting, `[some text]` for our remarks inside references — consistency — not
6. `*`/`**` instead of `_`/`__` — consistency, to support `_` in refs — not
7. `https` instead of `http` — security — greppable
8. strip whitespace — easier to read — `git`
9. remove/replace non-printable chars — looks like they are present in the original standard draft so we can ignore them in the future — greppable
10. add missing punctuation — consistency, easier to read — partially greppable
11. use `>` instead of `""` for refs — easier to read, better highlighting — not
12. empty line before a quote — consistency, easier to read in long explanations — greppable
13. `> ` instead of just `>` — consistency, easier to read — greppable
14. use `>` (right angle bracket + newline) for linebreaks in quotes — vanilla markdown syntax, idk why it renders correctly without them — not
15. try to preserve the original formatting in quotes — hightlighting, easier to match — not
16. always add a hint — if there's "No hint", the user loses his score for nothing — greppable
17. refer to `¶note-X` and `¶general-example-Y` directly where appropriate — no need to write `[*Note X*:` and `— *end example*]` — not
Contributor guide
Research direction
Start by reviewing the repository's existing question and explanation conventions, then compare each of the 17 proposed rules with current content. Done means a maintainer-approved, consistent set of formatting guidelines with clear scope and wording.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, markdown
- Domain
- content, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100