Merge pull request #294 from waldyrious/patch-4

rework/expand CONTRIBUTING.md

CONTRIBUTING.md

@@ -13,30 +13,21 @@ When setting up a brand new fork, run `make setup` to install the git pre-commit
 
 ## Guidelines
 
-Note that `tldr` is focussed on concrete examples.
+Note that `tldr` is focused on concrete examples.
 Here's a few guidelines to get started:
 
-- Focus on the 5 or 6 most common usages
-- When in doubt, keep new command-line users in mind
-- It's OK if the page doesn't cover everything, that's what `man` is for
-
-Token formatting:
-
-- Highlight user-provided values using the `{{token}}` syntax, for example `tar cf {{file}}`
-- For consistency in the tokens, use plain text descriptions (`{{source_file}}`) or short descriptive examples (`{{wallet.txt}}`)
-
-Common pitfalls / "donts"
-
-- Don't try to cover all possible examples, or combinations of flags (often, this is not possible without looking like `man`)
-- Don't explain general UNIX concepts that could apply to any command (ex: relative/absolute paths, brace expansion...)
-- Avoid catch-all examples like `tar {{options}}`
-- Don't group options as a trick to keep pages short (`tar {{c or x}}`)
+- Focus on the 5 or 6 most common usages. It's OK if the page doesn't cover everything; that's what `man` is for.
+- When in doubt, keep new command-line users in mind. Err on the side of clarity rather than terseness.
+- Try to incorporate the spelled-out version of single-letter options in the example's description.
+- Introduce options gradually, starting with the simplest commands and using more complex examples progressively.
+- Use short but descriptive values for the tokens, ex. `{{source_file}}` or `{{wallet.txt}}`.
+- Be specific: avoid explaining general UNIX concepts that could apply to any command (ex: relative/absolute paths, brace expansion, character escaping...)
 
 The best way to be consistent is to have a look at a few existing pages :)
 
 ## Markdown format
 
-For now, the format of each page has to match the following:
+The format of each page should match the following:
 
 ```
 # command-name
@@ -46,16 +37,16 @@ For now, the format of each page has to match the following:
 
 - example description
 
-`command -arg1 -arg2`
+`command -opt1 -opt2 -arg1 {{arg_value}}`
 
 - example description
 
-`command -arg1 -arg2`
+`command -opt1 -opt2`
 ```
 
-Eventually we might relax the format to accept any Markdown, but for now this has the advantage of adding some consitency between all pages, and making sure we focus on concrete examples rather than lengthy explanation of the different flags.
+User-provided values should use the `{{token}}` syntax, to allow clients to highlight them. For example: `tar cf {{file}}`
 
-The current format also works well for command-line clients that need to extract a single description/example.
+One of the reasons for this format is that it's well suited for command-line clients that need to extract a single description/example.
 
 ---------------------------------------