Simplify CI/CD Steps documentation

Insight

In https://gitlab.com/gitlab-org/ux-research/-/issues/2988+, users had a difficult time understanding how:

• Steps can be created by the pipeline author (aka the platform teams who manage all the shared CI syntax)
• Steps can be consumed by app devs (the developers and teams who consume the shared syntax)

Although we gave them an example of how an existing pipeline configuration file can be broken down into components and steps, they weren't able to get the full picture with the documentation examples. This impacted their ability to understand the syntax as well.

Supporting evidence

Dovetail insight

Ii I probably need to spend some more time with that steps, documentation. And, and understand it a little bit more.

Oh I think the I this this feels a lot like I don't I think that the, the thing that bumped me on this is the extra line here of the name. I'm not sure what this, what this does for you. I mean, you can just chain together the steps, the inputs, the steps, the inputs.

And so I'm not sure what's going on. Mhm. I'm familiar with GitLab’s syntax but this is I'm not familiar with this.

Action

Focus https://docs.gitlab.com/ee/ci/steps/ to show:

• a current CI yaml file with a super long & verbose script that is typically copied or referenced by app devs today.
• how to create a step in a repo to break that down and the benefits of this.
• breakdown of step syntax (simplified aka not including all the advanced things)
• how to incorporate steps back into the yaml file
• example of someone consuming the step and the benefits of this.
• all the additional advanced things users can do with steps!

Resources

• 🕊 Dovetail project
• 🔍 Research issue
• 👣 CI Steps Viable (&11525 - closed)

Tasks

• Assign this issue to the appropriate Product Manager, Product Designer, or UX Researcher.
• Add the appropriate Group (such as ~"group::source code") label to the issue. This helps identify and track actionable insights at the group level.
• Link this issue back to the original research issue in the GitLab UX Research project and the Dovetail project.
• Adjust confidentiality of this issue if applicable

Proposal

/ee/ci/steps/ - Steps at the highest level ("What is it?", "Do I have to use it? (no)")

• using_steps/ - Primarily for Sasha. How to add steps into a job. Shows the run keyword and how step references work. Answers questions like "Can I use steps in other repos?".
• debugging_steps/ - Still for Sasha. Addresses what to do when steps go wrong. The steps-specific stuff not covered in https://docs.gitlab.com/ee/ci/debugging.html. Includes how to run a job or step locally.
• creating_steps/ - Primarily for Priyanka. This shows how to structure a step.yml file. And the difference between exec and steps types. This will explain working directories, output files, etc...
• refactoring/ - Shows how to refactor a script into steps. This should start with the caveat that you don't have to do this. Nothing will break if you don't use steps. But it should highlight the benefits and walk through an example of how to incrementally decompose a script. This will include some overlap with using_steps and creating_steps, but specifically focused on the "onramp" use case.
• advanced_topics/ - This will be mostly for Priyanka also. This will cover how to refactor steps without breaking consumers. How to use the /internal folder for internal details. And this is where we will dive into the details of delegation (how to extend the core of steps with steps, and make steps "disappear").