From daef03a298a3bd4967eaed8b636cb93de2b42177 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 25 Aug 2015 01:16:26 +0100 Subject: [PATCH 1/2] rework/expand - merge do's and don'ts, since they had mostly the same advice - move token formatting info to the guideline section and the markdown section, as appropriate - tweak spelling and fix a couple typos - fix options vs. values in the formatting example, and add a token there. --- CONTRIBUTING.md | 33 +++++++++++++-------------------- 1 file changed, 13 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 62cf10c68f..5de8b5dabe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -- Your favourite command isn't covered? +- Your favorite command isn't covered? - You can think of more examples? Contribution are most welcome! All `tldr` pages are stored in Markdown right here on GitHub. Just open an issue or send a pull request and we'll merge it as soon as possible. @@ -13,24 +13,15 @@ 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 :) @@ -46,14 +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}}` + +Eventually we might relax the format to accept any Markdown, but for now this has the advantage of adding some consistency between all pages, and making sure we focus on concrete examples rather than lengthy explanation of the different flags. The current format also works well for command-line clients that need to extract a single description/example. From 918379c482979b1d1307391c804b2e35e02acc78 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 25 Aug 2015 04:07:19 +0100 Subject: [PATCH 2/2] remove obsolete paragraph also revert US/UK spelling change --- CONTRIBUTING.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5de8b5dabe..2c56fa560f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -- Your favorite command isn't covered? +- Your favourite command isn't covered? - You can think of more examples? Contribution are most welcome! All `tldr` pages are stored in Markdown right here on GitHub. Just open an issue or send a pull request and we'll merge it as soon as possible. @@ -27,7 +27,7 @@ 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,9 +46,7 @@ For now, the format of each page has to match the following: User-provided values should use the `{{token}}` syntax, to allow clients to highlight them. For example: `tar cf {{file}}` -Eventually we might relax the format to accept any Markdown, but for now this has the advantage of adding some consistency between all pages, and making sure we focus on concrete examples rather than lengthy explanation of the different flags. - -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. ---------------------------------------