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.

Yes, please. Your feedback on the above draft is much appreciated. Are you interested to give it a try? If you want, I can walk you through it by screen sharing and chat. Just let me know.

I’m on UTC 0 time zone, and fairly free between 21-22:30 hours Thursday/Friday 2-3 March.

Pop in to the Fedora chat in Documentation room 2023-03-02T21:00:00Z2023-03-02T22:30:00Z and 2023-03-03T21:00:00Z2023-03-03T22:30:00Z if anyone is interested.

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).