Fix some CI wording in documentation

What does this MR do?

• Adds definitions page to CI docs.
• Adds image of pipelines list (although currently missing border that is on other images).
• Changes CI to CI/CD in /doc and /doc/ci
• Sorts user documentation in /doc

Are there points in the code the reviewer needs to double check?

I'm not sure how to generate the border on the screenshot for pipelines. Pipelines is now mentioned in CI documentation, but it's still not mentioned from the doc root, so anyone who is confused by the new Pipelines tab still won't know where to look. I considered calling the link "CI/CD Pipelines", but stopped short.

Why was this MR needed?

Because grammar and confusion.

What are the relevant issue numbers?

Partially fixes #17733 (closed).

Screenshots (if relevant)

[Edit] Pulled grammar tweaks out to separate MR.

Reassigned to @axil

/cc @axil @ayufan

Added 2 commits:

• 49a9db5b - Add definitions and tweak some docs. Partially fixes #17733 (closed)
• fa93906c - Add pipeline image

Added 27 commits:

• fa93906c...bf4455d1 - 22 commits from branch master
• 57fcb772 - Tweak grammar
• bdcddea9 - Grammar and typographic changes to artifacts documentation
• f31b85d2 - Add definitions and tweak some docs. Partially fixes #17733 (closed)
• ba7a321d - Add pipeline image
• db439623 - Add CD

Marked this merge request as a Work In Progress

Milestone changed to %8.9

mentioned in issue #17733 (closed)

What do you think about adding an item called Pipeline which will have some text like Pipeline is a ... and links to CI/CD help items?

@blackst0ne An additional item or a replacement for the existing CI item?

@markpundsack, either rename CI/CD to Pipelines, or add new item Pipeline with short description what it is and links to the existing item CI/CD.

mentioned in issue #17686 (closed)

@markpundsack awesome! I'm concerned though about ci/definitions.md. If we are to merge the ci/contentns in the main docs as stated in the doc restructure issue https://gitlab.com/gitlab-org/gitlab-ce/issues/3349#note_12423207, where should we put definitions.md to make it apparent this is for CI?

@axil I was tempted to put the definitions at the top of the CI quickstart. If it doesn't fit in the quick start, maybe there could be another, deeper description of CI somewhere, and it would fit in there. Also, I'm tempted to make a Pipelines topic, which might alleviate the need for the definitions page to exist.

@axil What do you think about making top-level docs for Pipelines, Environments, and Deployments, each starting with some kind of defintion? Stages, Jobs, and Runners already have definitions in other pages. There's no definition for Builds anywhere, and we use the term inconsistently.

My secret plan is to kill the Builds view, then stop talking about builds as individual job runs.

I probably should have broken this up into smaller MRs so the grammar changes would get in without the risk in the other changes. I'll work on refactoring tomorrow.

I split out the grammar changes into !4772 (merged) so they can at least get in.

My secret plan is to kill the Builds view, then stop talking about builds as individual job runs.

I like this plan. I think that we should replace Builds view with Runners view to see the recent Jobs running or executed on your Runners :)

Added 822 commits:

• db439623...032e3983 - 819 commits from branch master
• a0fefc2a - Add definitions and tweak some docs. Partially fixes #17733 (closed)
• a1c2b168 - Add pipeline image
• edfe2e2d - Add CD

Added 2 commits:

• 41af86bc - Move Pipelines and Builds definitions to their own page
• a03cadcd - Move Pipelines and Builds definitions to their own page

Added 1 commit:

• 0582c085 - Add 'and builds'

@axil Rewrote it so there's no definitions page. Just created a new page for Pipelines and Builds. It's really bare at the moment. Could use some images. Also change some verbiage elsewhere to use the word "pipelines" where appropriate. Would appreciate another review to see if this is a good direction.

@ayufan @axil Do you know how to add the border around the images? I added a pipeline image to the quick start, but it doesn't have the borders:

Added ~149423 label

I believe this was on purpose. If you are not logged in, https://gitlab.com will redirect you to https://about.gitlab.com.

If you are logged in, that URL doesn't work though. You get: which is pretty horrible. I guess I can see the point though, if you aren't logged in, then this sends you to info about downloading. Still, I'd vote for dropping the sign_in part, unless we fix GitLab itself to not give you that ugly error. Most other sites would just redirect you to the logged in page if you try to log in when you're already logged in. Or display a login page so you can log in as someone else.

Ok let's leave it as-is then. This is a bug and I believe there is an issue open.

What do you think about making top-level docs for Pipelines, Environments, and Deployments, each starting with some kind of definition?

That would be cool, yes.

Reassigned to @markpundsack

I ended up making "Pipelines and Builds" and "Environments and Deployments" because they were related, and the pages looked tiny if I put them by themselves.

Added 1 commit:

• 82b32c28 - Fix link

Reassigned to @axil

Unmarked this merge request as a Work In Progress

Status changed to merged

mentioned in commit 39c43463

Picked into 8-9-stable, will go into 8.9.1.

Removed ~149423 label

mentioned in issue #18970 (closed)

mentioned in commit bdaced56

note: [stages] (batches) is bad combination of markdown, it would mean [stages] links to (batches) so the word (batches) will not appear as rendered sentence

don't know how to "escape" this