GitLab Web IDE beta

Have you tried Web IDE beta in GitLab?

I have been pondering about making video tutorial for new contributors working on Fedora projects (repo) in GitLab. My ideas are much influenced by @py0xc3 @pboy @darknao , and Web IDE beta release in December 2022.

I wrote a rough segment sketch before I make video script and screen recording.

See Snippet here.

design team, or to anyone who has creative mind and passion, I appreciate your feedback.

1 Like

Thatā€™s a great idea!

Concerning the points you noted in GitLab:

Restructure the casual contributor guide in sequential order
...
Shorten the sequence, if possible

I guess we can exploit synergies here. Generally, the guide should be in sequential order. If this is not the case at some point, we should definitely change this and adjust the guide to make it sequential again. Maybe we broke the sequences in the recent updates?

The same for shortening the sequence: unfortunately, the changes in GitLab have forced us to expand the guide, but I would love to make it ā€œ7 stepsā€ again some day (or at least get closer to 7 than now).

If there would be a video tutorial, we could add it in a TIP box to the beginning of the guide.

What I mean by putting the guide in sequential order is my way of reverse-engineering and breaking things down (like dismantling test sample).

Iā€™m not saying the guide is in wrong order, but some of step is not in equal section level (H2, H3).
Some of ā€˜clicksā€™ is a step on its own right whereas some H2 section is blended in a paragraph. Not all ā€˜clickā€™ is a process step.

We will have to wait for next releases until May and reiterate the process on every release.

Shortening the sequence is reiteration process to make the story telling concise in visual content.

Sure, Iā€™m looking for synergies on content reuse and update.

Ah, now I got it :wink:

Concerning the levels (H2, H3), I guess you mean that the second section is only H2 and all following sections H3. In the original version, that was intended. But with your comment in mind, I have to admit that this no longer fits the guide and can confuse people who read/write in the asciidoc source: I have aligned all H2 and H3 to H2 with Commit 30efc2ac. Thanks for making me aware of the issue!

Four process groups are created;

  • Search project
  • how to create a fork
  • commits
  • merge request
1 Like

Here is a draft video script for your comment and ideas.
Merge request process is still work in progress to write in full sentence.

Fork a project (in plain English, copy project)

If you make your first contribution and you do not have write access for the repository you want to contribute to, you need to fork a project.

A fork is a personal copy of the repository, which you create in your namespace. A namespace provides one place to organize your personal or group projects. Press fork redirects you to ā€˜Fork projectā€™ where you create a new fork. Your personal namespace is your user name. Go to Project URL and select your namespace on drop-down menu.

Launch Web IDE

On the project landing page, press . (dot) to launch Web IDE. Alternatively, Web IDE button is visible to click away. Getting started walk-throughs help you familiar with key features.

Navigate project directory in left pane of Web IDE. Click through modules/ROOT/pages directory path and select a file to edit. Start editing file with defined markup syntax.

Track changes

You can see which files will be changed underneath the commit & push button. It works like git status and git diff commands. Press source control button (branching icon) and click changes to track changes with side-by-side view.

One-click commit and push

After you complete editing document, click source control button (branching icon) on left pane.

You will be prompted to enter commit message. Click commit & push.

NEW-changes

If you click Yes, create a new branch with a specific name for the branch to commit that fixes issue. If no, select current branch to continue editing the file.

NEW-branch

Merge request (in plain English, review and approve changes)

Merge request promotes collaboration between writers and reviewers.

Quality check before pushing changes to website

Once merge request pipeline passed, click view app to see rendered pages for quality check.

Beta user feedback

If you want to share feedback (suggestions for new features or unexpected behavior), head over to GitLab issue board specific to Web IDE beta.

I canā€™t contribute much to the Web Interface, because I prefer the local authoring environment. But 2 comments

  1. Working with forks has not only to do with commiting privileges, but above all with working style. We want to ignite discussions and reviews that way.
  2. Videos are sometimes faster to follow than (cumbersome) descriptions. Sometimes itā€™s the other way around, too. How about combining the two? So fade in short video snippets at the appropriate places in the text? That might also be easier in terms of video and better to keep up to date.

Web IDE workflow is another way to contribute. So for me, the tool is not an ā€˜either orā€™ question.

I use local environment when I need to render document in my web browser (example: link changed, nav.adoc changed, style/header change applied, complete rewrite of documents).

Web IDE is to fix minor issues where I donā€™t need preview. Web IDE workflow makes forking process approachable to non-developers. The advantage of using Web IDE is I can work with any computers or tablets as long as I have a web browser. The new Web IDE is a great tool as a bridge to remote development. We need to give paths for growth to contributors, who are aspiring or pro developers as well as non-developers.

It will be short, so splitting down it to a few pieces and interlace them around existing pages will be cumbersome to maintain. So no.

Videos are complementary tutorials to express flow of actions much better than screen shots.
Voice over, transcript/video caption will be added so it can be presented standalone, not interlaced with existing pages.

The reason why I started with video script is maintenance of video tutorials/version control.

Maybe we should expand this to a tools overview page (menu item ā€œcontribution toolsā€?

I would leave the decision to a later stage once we get enough traction and interest in this thread.

There are three unused links in the menu item and they appear overcrowded already, which do not give clear signpost to contributors (existing and new alike). Expanding the menu item will cause decision paralysis.

About tasks required for screen recording and moderation for content, Iā€™m looking forward to feedback from Web IDE users or someone who is interested to give it a try.

I learn as I go along, so I get hands-on with Kdenlive (screen grab) for recording and editing.

Any feedback about screen recording and tutorial process will be appreciated.

Please let me know for doing early trials.

Early trials equal to beta? Could you elaborate what you mean by that?

Whatever workflow I settled in for writing and reviewing docs, I aim to:

  • Preview docs predictably in local build or in GitLab
  • Push docs with a few clicks or commands (the fewer, the better)
  • Drag and drop images into source file, not wrestling with esoteric image macro
  • Fix merge conflict or pipeline failure interactively without changing context/tool

Of your scripts / videos.

If you want feedback from a non-developer.

1 Like

Here is some update on contribution guide using GitLab tools (Web IDE and live preview during MR). The new page went live 22 March. :party:

Please let me know what you think and give it a try yourself. All you need is your GitLab account linked to Fedora account and your web browser.

I will work on video version of GitLab user guide for docs contributions, using screen grabbing with Kdenlive. Maybe Iā€™ll experiment voice over and caption.

1 Like

Hi, I need to work on scripts over next weeks after my PTO (27-31 March).

Hi folks!

Issue created to track progress.

Here are steps to create video tutorial.

Completed

  • Plan tutorial
  • Build consensus and get feedback
  • Complete video script
  • Screen recording test and setup

In progress

  • Recording and editing

In plan

  • Share a draft video at Peertube
1 Like

Hi Folks,

Iā€™m sharing screen recording - Fedora Docs team contributor tutorial video Part 1.

Video is for preview and your feedback. Unedited. No sound or fancy effects.

Duration: 4m 40s

Video script - How to make light edit under 5 minutes

== Part 1. How to fix inactive link and navigate to Fedora Docs editing tool

  • Go to User Documentation on the lower right corner from the new Fedora Website - Fedora Start | The Fedora Project

  • Click system upgrade on the left pane

  • Read the docs and check if the link works correctly

Example: Automatic upgrade using dnf system upgrade

Link: Upgrading Your Current System :: Fedora Docs

  • If the link does not open the page, check the URL and file name

  • Press the ā€˜Edit this Pageā€™ button on top-right corner to go to GitLab

Note: To simplify the content, this video skipped GitLab authentication process.

== Part 2. How to use Web IDE

  • Click the blue ā€˜Web IDEā€™ button

  • Create a new fork and a branch

  • Create a new branch and switch to it. See status bar

To create a branch from the current branch in the Web IDE Beta:

  • On the status bar, in the lower-left corner, select the current branch name.
  • From the dropdown list, select Create new branchā€¦.
  • Enter the branch name.
  • Press Enter.

Are you sure you want to checkout ā€œbranch-sequenceā€? Any unsaved changes will be lost.

  • In editor on the right, Scroll through which line is causing the problem
  • (In this case), check the different repository the page references to
  • Edit the line or start writing
  • Save your work with Commit & Push
  • Push to current branch (you created)
  • Press the ā€˜Create MRā€™ button that redirects to GitLab MR creation UI
  • Open merge request
  • Add MR descriptions what your MR fixes

You will see the following message.

ā€œReady to merge by members who can write to the target branchā€.

  • Your MR is successfully submitted for review. Check the progress in 48 hours.
  • If you receive a comment, revise your MR to improve or fix anything you overlooked

Thanks for your contribution.

Credit and Acknowledgements

Software used for recording

  • Fedora KDE Plasma 38 Scientific Lab
  • GitLab Free tier 15.11 Release
  • Firefox 112.0.1 Alpenglow theme
  • Open Broadcaster Software (OBS) Studio 29.0.2

Repost by a GitLab developer

(LinkedIn, Mastodon, Twitter).

1 Like