From 040705a7bd0e727236a582df9ea7a5b158220722 Mon Sep 17 00:00:00 2001 From: Managor <42655600+Managor@users.noreply.github.com> Date: Sun, 11 May 2025 14:39:56 +0300 Subject: [PATCH] CONTRIBUTING: add a link to style-guide and clarify option usage (#16459) * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md Co-authored-by: K.B.Dharun Krishna --------- Co-authored-by: K.B.Dharun Krishna --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 631ce30703..ee59932973 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,7 +41,7 @@ Here are a few guidelines to get started: Remember, it's OK if the page doesn't cover everything; that's what `man` is for. 2. When in doubt, keep new command-line users in mind. Err on the side of clarity rather than terseness. For example, commands that require `sudo` should include it directly in the examples. -3. Try to incorporate the spelled-out version of single-letter options in the example's description. +3. Prefer using longform options or try to incorporate the spelled-out version of single-letter options in the example's description if the program doesn't support longform. The goal is to allow people to *understand* the syntax of the commands, not just *memorize* it. 4. Introduce options gradually, starting with the simplest command invocations and using more complex examples progressively. 5. Focus on details specific to the command and avoid explaining general UNIX concepts that could apply to any command @@ -52,6 +52,8 @@ Use proper judgement, keeping simplicity and user-friendliness as the top priori When in doubt, have a look at a few existing pages :). +See the full [style guide](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/style-guide.md) for detailed instructions. + ## Directory structure The English pages directory is called `pages`, under which the platform directories are present. Language-specific directories must follow the pattern `pages.`, where `` is a