editing pass from the docs team

[holdenhewett]

Description

Thanks for your contribution! Please see the following feedback and suggestions that I've submitted in this PR to align this doc with Shopify's dev doc quality standards (see Content Help documentation):

General feedback:

Content organization

1. The introduction would be more helpful to readers if it contained additional context such as:
   1. When/why someone would want to configure Redis using a ConfigMap.
   2. A concrete example (this is an opportunity to explain the "real world" example on this page).
   3. A summary of what readers should expect while following this tutorial.
2. Section headings
   1. Change the "Objectives" section heading to "What you'll learn" and add a short intro to the list.
   2. Change the "Before you begin" section heading to "Requirements" and make the content more concise and concrete by using a list and links to important topics for each list item.
   3. Break up the "Real World Example: Configuring Redis using a ConfigMap" section into a few smaller sections instead of one large section. This will help reduce overwhelming newer users and make the tutorial more readable, especially if they don't complete the tutorial in one go. I suggest creating the following sections to accomplish this:
      1. Step 1: Create a ConfigMap
      2. Step 2: Deploy the Redis Pod
      3. Step 3: Inspect the initial configuration
      4. Step 4: Update the ConfigMap
      5. Step 5: Apply the updated configuration
      6. Step 6: Inspect the new configuration
      7. Step 7: Clean up resources

Content style

1. Add numbered lists throughout the doc. Doing so will clearly mark each step in the process, improve the guided experience of the tutorial, and be consistent with Shopify's other tutorials.
2. When addressing the reader, it's best do the following to enhance clarity and avoid the awkwardness of them thinking someone is there with them during the tutorial (you are not with the reader):
   • Talk to the reader and not about them using second person terms like you, you'll.
   • Exclude yourself by not using terms like use I, I'll, me, we, we'll, us, let's, etc.
   • When referring to Shopify as an entity, it's OK to use "we". For example, use either "Shopify recommends that you ..." or "We recommend that you ...".
3. Several sentences and list items are missing periods at the end of them.
4. If a term or concepts has a glossary entry, use the glossary template when introducing new terms or concepts for the first time.

Accessibility and usability

1. Where applicable, replace "above" and "below" with "preceding" and "following" respectively. Using terms like above and below makes it difficult for those using assistive technologies like screen readers to understand precisely what is being referred to. If the term isn't referring to something that immediately precedes or follows the content being read, it's more appropriate to link directly to what you're referring to instead. This coincides with breaking the main section into several sections for better linkability as well!
2. Some links can use more context around them and different link text to make them more accessible. This is key to helping readers understand where they'd go when clicking the link and also why they may want/need to do so.
3. For tutorials, it's best to use less complex methods of file creation like using cat and a here document (<<EOF) to redirect the output to a file. Instead, just instruct readers to create the file and to add the code snippet's content to it. Removing this complexity will help more novice readers focus on what they're learning in the tutorial and not get distracted by unnecessary complexity.

Source code formatting

1. I suggest using consistent heading formats throughout the doc with regular Markdown headings to reduce complexity. Using a combination of custom templates and semantic Markdown for headings may be confusing for contributors, especially if there's no difference in the rendered output.
2. I highly suggest using the highlight template for code snippets instead of the semantic Markdown when you need to refer to specific lines in them. This will better draw attention to lines that you call out in the context surrounding the code snippets.
3. Using the {{% code_sample file="pods/config/redis-pod.yaml" %}} template works, but it lacks the ability to highlight specific lines of code like a highlight template does. Being able to highlight lines in longer files is especially useful to get readers looking directly at what's important instead of having to search for it.