Skip to content

Commit 0499334

Browse files
zimegmwbrooks
andauthored
docs(maintainers): style guide adds help arguments use opinionated brackets (#459)
Co-authored-by: Michael Brooks <mbrooks@slack-corp.com>
1 parent 85f4729 commit 0499334

1 file changed

Lines changed: 26 additions & 0 deletions

File tree

.github/STYLE_GUIDE.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ A current suggestion for how Slack CLI inputs are handled and outputs are format
55
- **Input**
66
- [Prompts are Flags with Forms](#prompts-are-flags-with-forms)
77
- **Output**
8+
- [Help Arguments use Opinionated Brackets](#help-arguments-use-opinionated-brackets)
89
- [Help Descriptions find Complete Sentences](#help-descriptions-find-complete-sentences)
910
- [Section Formats with Command Headings](#section-formats-with-command-headings)
1011

@@ -24,6 +25,31 @@ A flag option should exist for each prompt with a form fallback. Either default
2425

2526
Results of a command go toward informing current happenings and suggesting next steps.
2627

28+
### Help Arguments use Opinionated Brackets
29+
30+
The square brackets surrounding command arguments hint that these are optional:
31+
32+
```
33+
USAGE
34+
$ slack env add [name] [value] [flags]
35+
```
36+
37+
The angled brackets around arguments hint that these are required:
38+
39+
```
40+
USAGE
41+
$ slack <command>
42+
```
43+
44+
Optional and required arguments can be mixed-and-matched:
45+
46+
```
47+
USAGE
48+
$ slack <command> [args] [flags]
49+
```
50+
51+
These examples have meaningful argument placeholders and sometimes forms as fallback.
52+
2753
### Help Descriptions find Complete Sentences
2854

2955
The output of extended help descriptions should be complete sentences:

0 commit comments

Comments
 (0)