Docs meeting agenda: 2023-01-18

Here’s the agenda for the meeting 2023-01-18T19:30:00Z in #fedora-meeting-1:

  • Announcements
  • Action item followup
  • Tickets review: 2 tickets are currently flagged for the meeting on GitLab
  • Quick docs update
  • Your topics here!
  • Open floor
1 Like

I’ve got back to back meetings all day so I won’t be able to make this meeting.

I’ve got the first draft done for the update to the Installing from Source Quick Doc. I’ll try to have that finished up this weekend.

2 Likes

I can’t join today’s meeting due to other commitments.

I’ve done the first draft of finding and installing application guide, which is rewritten. I uploaded the file onto Pagure issue board. I’ll add link to images and other pages and that’ll be ready for PR this weekend.

2 Likes

We have a meeting tag in QD repository, too:

https://pagure.io/fedora-docs/quick-docs/issue/111

It’s about how to handle a very long article.

1 Like

Minutes and full logs are available.

Highlights

All Quick Docs PR have been processed and the list is now empty! ( new contributions are welcome :wink: )

Action

  • pboy to try the -b (build) & -p (preview) options of docsbuilder on mac

Well, I did that and got:

Site generation complete!
Open file:///antora/public/index.html in a browser to view your site.
The preview will be available at http://localhost:8080/
docker: Error response from daemon: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: error mounting "/host_mnt/Volumes/Projekte/FedoraRepos/quick-docs/nginx.conf" to rootfs at "/etc/nginx/conf.d/default.conf": mount /host_mnt/Volumes/Projekte/FedoraRepos/quick-docs/nginx.conf:/etc/nginx/conf.d/default.conf (via /proc/self/fd/14), flags: 0x5001: not a directory: unknown: Are you trying to mount a directory onto a file (or vice-versa)? Check if the specified host path exists and is the expected type.
Please run ./docsbuilder.sh -k to stop the preview server
pb@Peters-iMac quick-docs % ls -l

With the previous ./preview.sh everything worked well with docker. I use Docker Desktop 4.16.2

Any idea?

Not sure if you have currently more important things to do, so feel free to remove it again from the agenda, but maybe you could have a short elaboration tomorrow about the team’s preference about this:

The question is what to use in future in the casual contribution guide (formerly, 7-steps): the new UI, the old UI (which needs to opt-out), or to switch to the traditional editor.

Summary: GitLab changed by default to the new UI, which seems to be not optimal for our purposes (@hankuoffroad did already some initial testing, thanks for letting us know about your experience!). If one wants to use the old UI, other steps have to be added to opt-out. A draft for the new UI is already in development (see the MR) by @anthonymcglone (thanks for taking care Anthony!), but given the possibility that further changes are made in the coming days and weeks (the new UI is still beta) and the increased complexity of the new UI, the team might also consider to switch to the old editor, which is still offered as alternative to the more sophisticated UIs. Yet, we do not know if everything but the new UI will be deleted once the new UI is released. So no optimal solution atm.

Maybe it makes sense to capture the team’s preference before fully implementing any of the possibilities, just to ensure everyone is working towards the same direction and that all are on the same page. Just to avoid double work and such.

Opt out is only temporary until April and May when the new UI replaces the old by new GitLab release. For simplicity, we need to change to the new UI in our docs as soon as possible.

Although it is beta, the basic features will stay. Any changes gravitates towards plug-ins and development tools/workflow.

@hankuoffroad , in this case, the traditional GitLab editor is the only alternative to the new UI. I have myself not yet had the time to compare both. But given your indication in the other thread, that might be a more suitable alternative? It is very simplistic and does not impose many clicks on the user. But I’m not really in the situation to make a guess about your current needs atm.

So, if you wanna compare/test: when you are at the point where you can click the blue button “open in web ide”, there is a little arrow at the right of the blue button. There, you can switch to “edit”. This will then open the traditional editor instead of the new UI.

To avoid confusion: the traditional GitLab editor and the old Web UI are two different things.

1 Like
  • the traditional GitLab editor: ‘Edit’ button
  • the old Web UI: Web IDE (old)
    Correct?

A choice is for potential users and contributors. My preference is secondary. We will have time to discuss in the meeting or in Discussion.

Generally, you are right. But given that people are already afraid of GitLab, the goal was in the “casual contributor” HowTo to free users from too many choices but offer them what is most easy & simple (and shortens the HowTo): this limits the steps they need to conduct (and read through) and thus, lowers the barrier to contribute.

If we add both possibilities (new UI + traditional editor) to the HowTo, this would make the HowTo much longer, more complicated (they have to identify a proper choice before contributing), and users who open the guide (and are likely to first skim through it) could be “too impressed” by the many information and choices they have to work through for a simple contribution. Git itself is already deterring for many.

So to avoid such issues was the idea that made us originally to focus on “one way” in the guide. Don’t forget: if we add both possibilities for casual contributors, this would double the size of the guide since most steps would be contained twice, once for each possibility.

My personal opinion (which is as probabilistic as any other) is to stick with one possibility in the HowTo, in order to avoid the impression of complexity for casual contributors when skimming the HowTo (and to avoid choices in situations in which users feel already insecure). But as you indicated, this implies the disadvantage that the team decides for the users. All just compromises.

Since you said that the old web UI will be removed soon, the remaining choices that will remain on the long term are:

  • new web UI (the one that is currently in beta)

  • traditional editor (which is not the old web UI)

Looking forward to the team’s decision. Unfortunately, I cannot attend today.