Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

(design_proposal): chef cli catalog #877

Merged
merged 15 commits into from
Feb 21, 2020
+240 −0
Merged

(design_proposal): chef cli catalog #877

Changes from 1 commit
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
7cdefd5
(design_proposal): chef cli catalog
Jan 20, 2020
65535fb
(docs): update estimate of wait time
Jan 23, 2020
f062d55
doc:(update) review comments
Jan 27, 2020
a1ab772
doc:(telemetry) link
Feb 7, 2020
38443fa
doc:(review) marc and afiune
Feb 14, 2020
6df8dc1
doc(refinements): pairing session with @marcparadise
Feb 18, 2020
a9ac173
update(png): new mocked-chef-help-command.png
Feb 18, 2020
fd7bb8d
update(png): new chef-top-level-command.jpg
Feb 18, 2020
7fb5f95
review(push-archive) merge with chef-policy push
Feb 19, 2020
7255d7f
Apply suggestions from code review
Feb 19, 2020
3844264
doc(review): correct verbiage Use:
Feb 19, 2020
b653d2f
Merge branch 'master' of https://github.com/chef/chef-workstation int…
Feb 20, 2020
db5616d
section:(docs) automation of reference docs
Feb 20, 2020
3d9c0df
doc(tech_writer): update motivation
Feb 20, 2020
4bcc349
doc(last): docs comments
Feb 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/Chef-CLI-Catalog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,6 +204,19 @@ Experimental Commands:
analyze Analyze artifacts from a Chef Infra Server
```

### Automation of reference documentation

Motivation:

As a technical writer
I want to add examples to the chef catalog documentation
so that users will know the tricky bits and we the documentations gets updated automatically as the code evolves

The documentation team is working towards meaningful automation of our reference
documentation, this includes our CLI tools. This proposal includes working with
the documentation team to implement an automation inside our `chef` catalog by
adding and example field that can handle command line examples.

### EXTRA: Present correct usage of sub-binaries

An additional task from this proposal is the use of an environment variable that
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Talked with Salim about this - IMO, our first implementation should reference chef policy in all the help text. This makes it more confusing for our effortless developers who will directly invoke the chef-policy binary (without all the overhead of the entire Chef Workstation ecosystem). But those are internal users we can help.

In the future I could see us developing a Golang effortless executable that functions similarly to the chef golang executable. It allows us to start creating a custom workflow for them, leveraging tools under the covers that they do not care whether are written in Ruby or Golang. At that time I would introduce some kind of environment variable that would allow the help text to display chef policy or effortless policy.

Expand Down