knatten / knatten/cppquiz

Add guidelines for formatting questions and explanations

Open
#357 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.