Fix indentation inside Code Examples

[dtinth]

Why:

In the Code Examples section, the YAML shown looks like, but is not, a valid GitHub Actions workflow file. The schedule: section is inside the on: where the docs shows it as a separate block.

What's being changed:

The indentation has been fixed to make the code example a valid workflow.

This helps the reader understand the context better that schedule: is not a standalone block, but is supposed to be in the on: section. It also prevents attentive readers from getting distracted by invalid YAML syntax in the code block while reading the guidelines.

Check off the following:

• All of the tests are passing.
• I have reviewed my changes in staging.
• For content changes, I have reviewed the localization checklist
• For content changes, I have reviewed the Content style guide for GitHub Docs.

[welcome]

Thanks for opening this pull request! A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[janiceilene]

Thanks for opening a pull request @dtinth! I'll let the @github/docs-content-ecosystem team know this is ready for review 🌟

[rachmari]

@dtinth thank you for updating these docs. 💚 🙌

I had one very minor request. Once you address that, we can merge this in! 🚀

[rachmari]

Because we always start code blocks without any indentation, what do you think about reverting the indents on lines 128 and 129?

So the code example would be:

Use

on:
  schedule:
    - cron:  "40 19 * * *"

Avoid

schedule:
  - cron:  "40 19 * * *"

[dtinth]

@rachmari I think we just ran into a paradox 😂… As the code block in question is about “what to avoid” (which in my opinion should be exempt from the guideline).

• The rule to “start code blocks without any indentation” also reinforces the guideline being addressed (to include the necessary context in code samples). Without the indentation the code example wouldn’t make sense; see the next point…

• In workflow files, schedule is not a top-level property; it must be nested inside the on: block. YAML is whitespace-sensitive so removing the indentation will make the workflow file invalid. To show a valid part of a valid workflow file (which is what I am trying to convey) the indentation must be kept intact.

  ⬇️ This is not part of a valid workflow file (due to the missing indentation), so it might not be a good example...

  Avoid

  schedule:
    - cron:  "40 19 * * *"
  

  ⬇️ This is part of a valid workflow file but not following the guideline because the context is not included...

  Avoid

    schedule:
      - cron:  "40 19 * * *"
  

Let me know what you think. If you disagree with this I will make the changes as requested. Thanks!

[rachmari]

@dtinth, I see what you mean here about the paradox. 😂

The purpose of the style guideline is to let contributors know that when using code examples logical boundaries of the code example should be included. For example, if it were a javascript code sample it might be most relevant to include a whole function rather than a snippet inside a function. This specific example is referring to a GitHub Actions workflow file and specifically highlighting that you should include the top-level property on that schedule is related` to.

Sometimes we don't use the whole GitHub Actions workflow but just refer to steps. In that case, we ensure that we include the steps property at the top of the file.

for example:

steps:
 - name: My first step
   if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
   run: echo This event is a pull request that had an assignee removed.

I suggested not indenting the Avoid example because it would conflate two style guidelines in one example. This specific example is referring to the guideline to show logic boundaries in code samples, not to avoid indenting the first line in a code sample. I think that would be a new style guideline.

[dtinth]

@rachmari Thanks for taking time to explanation the rationale. 🙏

Having seen other parts of the docs, this now becomes clear that indentation in an action’s subsection is omitted. I have fixed the Avoid section in the code example as you suggested. 😃

[rachmari]

@dtinth

Having seen other parts of the docs, this now becomes clear that indentation in an action’s subsection is omitted.

I think the underlying issue is that we're not specific enough about what this guideline means in our style guide. We should improve that in the future.

[rachmari]

@dtinth this looks great. Thank you for your contribution and the chat! 🙌 I'll get this merged right away. 🚀 🤘

[github-actions]

Thanks very much for contributing! Your pull request has been merged 🎉 You should see your changes appear on the site in approximately 24 hours.

If you haven't already, you can add yourself to the list of contributors by creating a new comment in this PR using these instructions. Thanks again! ✨