Jira (BOLT-968) Document available Bolt transports

[Kate Lopresti (JIRA)]

Abir Majumdar created an issue

Puppet Task Runner / BOLT-968 Document available Bolt transports Issue Type: Task Assignee: Unassigned Created: 2018/11/07 9:09 AM Labels: DOCS Priority: Normal Reporter: Abir Majumdar From HipChat:  A customer was asking me if bolt could be run over the puppet protocol. So I wanted to send the link to the docs, and a direct answer was harder to find than expected. First, I expected a pcp example in the "Running basic Bolt commands" but there isn't one. Next, under Transport under "Bolt command reference" the list of acceptable values for '--transport' aren't listed. Similarly, under "Set a default transport" under "Adding options to Bolt commands" pcp isn't mentioned. There is the page "Configuring Bolt to use orchestrator" but if I'm new to Puppet I have no idea what the "orchestrator" is (it's also buried under Configuring Bolt). Available transports are listed in the `bolt --help` output, but not the docs.   Add Comment

This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93)

[Michael Smith (JIRA)]

Michael Smith updated an issue

Puppet Task Runner / BOLT-968 Document available Bolt transports

Change By: Michael Smith Sprint: Bolt Ready for Grooming

Add Comment

[David Kramer (JIRA)]

David Kramer updated an issue

Puppet Task Runner / BOLT-968 Document available Bolt transports

Change By: David Kramer Sprint: Bolt Ready for Grooming Kanban

Add Comment

[Melissa Amos (JIRA)]

Melissa Amos assigned an issue to Melissa Amos

Puppet Task Runner / BOLT-968 Document available Bolt transports

Change By: Melissa Amos Assignee: Melissa Amos

Add Comment

[Melissa Amos (JIRA)]

Melissa Amos commented on BOLT-968

Re: Document available Bolt transports This has been added to docs.

Add Comment

[Garrett Guillotte (JIRA)]

Garrett Guillotte commented on BOLT-968

Re: Document available Bolt transports

Melissa Amos Do we have an ETA for when the changes described in the ticket will go live, or any information about what was changed? For instance, I don't see these changes on docs-preview or docs-internal:

First, I expected a pcp example in the "Running basic Bolt commands" but there isn't one. Next, under Transport under "Bolt command reference" the list of acceptable values for '--transport' aren't listed. Similarly, under "Set a default transport" under "Adding options to Bolt commands" pcp isn't mentioned. There is the page "Configuring Bolt to use orchestrator" but if I'm new to Puppet I have no idea what the "orchestrator" is (it's also buried under Configuring Bolt).

If those changes aren't going to be made, can that be acknowledged for future reference?

Add Comment

[Melissa Amos (JIRA)]

Melissa Amos commented on BOLT-968

Re: Document available Bolt transports

Garrett Guillotte I made the changes in the PR in docs. Bolt docs are largely written by Engineering, so I'll defer to Alex Dreyer about adding this additional content^.

Add Comment

[Alex Dreyer (JIRA)]

Alex Dreyer commented on BOLT-968

Re: Document available Bolt transports

+1 to adding pcp to "Set a Default Transport" list since that list is already there. I don't think we want to duplicate config option choices too much between the command reference and config reference sections. My opinion is that users will not be successful using the pcp transport unless they start with the "Using Bolt with Puppet Enterprise" page. It's simply too complex and finicky to include for users to discover and use successfully without starting there. I'd rather not bog down too many bolt docs sections with PE only information that if taken in isolation is likely to result in users hitting cryptic error messages. Therefore I don't think it belongs in the "Running basic commands" section. Would moving the "Using Bolt with Puppet Enterprise" to be a top level section be enough to improve discoverability?

Add Comment

[Garrett Guillotte (JIRA)]

Garrett Guillotte commented on BOLT-968

Re: Document available Bolt transports

I don't think we want to duplicate config option choices too much between the command reference and config reference sections. Are all of the config options available on the command line also always available as config file options? If so, is there a reason to document them separately? For instance, in OSP where config options can be passed via both puppet.conf and as CLI flags, there's the configuration reference describing the options, and a separate topic on different ways to pass those options, and which methods take precedence.

Add Comment

[Cas Donoghue (JIRA)]

Cas Donoghue updated an issue

Puppet Task Runner / BOLT-968 Document available Bolt transports

Change By: Cas Donoghue Release Notes: Not Needed

Add Comment

[Cas Donoghue (JIRA)]

Cas Donoghue updated an issue

Puppet Task Runner / BOLT-968 Document available Bolt transports

Change By: Cas Donoghue Fix Version/s: BOLT Next

Add Comment

[Alex Dreyer (JIRA)]

Alex Dreyer commented on BOLT-968

Re: Document available Bolt transports

We have not followed the puppet pattern of exposing every possible config option from the CLI. Some CLI flags especially around logging don't map directly to specific configuration options either.

Add Comment

[Melissa Amos (JIRA)]

Melissa Amos updated an issue

Puppet Task Runner / BOLT-968 Document available Bolt transports

Change By: Melissa Amos Labels: DOCS docs_reviewed

Add Comment

[Austin Boyd (JIRA)]

Austin Boyd updated an issue

Puppet Task Runner / BOLT-968 Document available Bolt transports

Change By: Austin Boyd Zendesk Ticket IDs: 33798 Zendesk Ticket Count: 1

Add Comment