Follow-up from "Split docs for GLEX and experimentation.rb"

In the spirit of MVC, @aqualls is moving these discussions from !56052 (merged) so that large MR can be merged:

  • @jejacks0n started a discussion:

    Moved everything above into a nested markdown file, and provided the links to both pieces of documentation.

  • @jejacks0n started a discussion: (+1 comment)

    /cc @gitlab-org/growth/experiment-devs @cwoolley-gitlab @pslaughter

    I tried to hit all the important topics, but there are still several not added here.

    https://gitlab.com/gitlab-org/gitlab/-/blob/b074fc07f2ff11a9c26a686276353db20ac886df/doc/development/experiment_guide/gitlab_experiment.md

    Notably missing is that the client layer is in heavy flux right now, and I haven't worked on that aspect at all. The idea there is to track all experiment contexts (that were run during the request) on all client side events, which covers events and simplifies the documentation of it. Then we should just provide a simple mechanic for doing experiment branching by variant -- probably for vue and vanilla cases?

    Anyway, please review at your leisure and let me know if there's anything I might have missed that would be helpful.

  • @aqualls started a discussion: (+4 comments)

    @jejacks0n I just pushed two hefty commits. I added hard line wraps in the first commit, so that I could point you to the second commit to make reviewing easier for you.

    First up, what I did:

    • Remove code tags from page titles - they're problematic
    • Lots of line breaks. (I did that first to reduce the possibility of merge conflicts)
    • Rephrase to active voice
    • Work on wordiness
    • Fixed NOTE display whenever possible - notes don't support multiple paragraphs, or lists. (Here's how to do it: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#alert-boxes)
    • Remove future tense in favor of present tense
    • Add current release to mentions of "currently in flux" so Later Us knows when we wrote this information.
    • Revised (most) subheadings to remove gerunds (words ending in -ing)

    What I need:

    • A brief read-through to ensure my wording changes didn't change the meaning.
    • In doc/development/experiment_guide/experimentation.md I tried to fix the nested list items, and I'm not sure I got it 100% right. I'd suggest you use the review app to check the display. (I just kicked off the job to start the review app.)

    I know this was a beast of an edit - as I write this, I'm pushing a subsequent commit to fix the anchor link I broke when I shortened a subheading title.

    Approving and sending back to you - I want to make sure you're ok with these changes instead me just merging.

  • @jejacks0n started a discussion:

    I realize that we are probably positioned well to shift away from ableist terms, so am starting to do that a bit here. Since this doesn't reference code "exactly" I'm going to change this here, and then come back with a new MR after changing some code.

Edited by Jeremy Jackson