7-click HowTo for Fedora Docs

I think I made much more images than necessary (as noted above, I already consider to remove at least one). I explained everything in detail that can be explained (this was at least my goal): it is now up to externals to give some incentives what is “obvious” and can be removed, and what not. My goal here was to NOT assume anything for obvious, because taking some things for granted was imho one of our mistakes in the past.

1 Like

There is nothing wrong with what you did. The detail is good.

The process itself just isn’t simple or easy.

Honestly, if the process was simple and intuitive it wouldn’t need any screenshots.

As technologists, I think we often lose track of how most of the world functions.

4 Likes

I agree… the process is not intuitive BUT I like the screenshots - For me as a not-so-technical person this made it easy to click along and shed some light into how things are done.
If it could be simplified - even better but for the time being thank you @py0xc3 for making the effort to create this!

4 Likes

I like to share my approach without screen capture in the same vein as your effort to help contributors in Docs. See this draft in HackMD.

The most difficult part of the workflow for non-git users is the git concept itself.

  • A mental model like branching out and merging back in
  • Collaboration workflow
1 Like

My goal here is to keep the branches away from external contributors to simplify the process. In our “experiment” (see the previous thread and the related MR in the GitLab issue), the branches were the major origin of confusion.

The branching of the web interface (so if you start at the Fedora Docs page “edit” button) creates always a merge request of F35/F36/… into main. This has to be changed in most cases but this can be done by one of us later, before accepting the MR. A review of the MR has to be done by us anyway, so this costs us 5 seconds (everyone who can accept MR, can also change the target branch by clicking on it within the MR). Imho, we can spare the user from this.

1 Like

I think, your text is perfect and ready to be published. It could be the first of the 3 ways to contribute as we decided about our new team page (and that I still have to restructure, try to do it until Wednesday).

Maybe you should add some short explanations of some terms as “fork”. Something like “make a copy, so you can’t break anything published, but system keeps track of its original and can perform steps to integrate modifications into the published text”.

IMHO, that is an important topic. I said that elsewhere as well. The current presentation is very elegant, but hard to find. Maybe, we could introduce 2 buttons below the table of Contents, one with the link to edit and one to your how-to.

1 Like

I like the HowTo, but see one problem that likely applies to all readers.

The images tend to blend with the text and make it hard to tell what is the image and what is the instructional/descriptive text. I suggest shrinking the images a little and possibly putting them with a contrasting border to better delineate the image from the text. Maybe even change the text color and/or color the background to help things stand out better.

I just worked through the steps described in this HowTo as a first time user/author and it seems to fit the need very well.

1 Like

Well, we can’t do much about that. All docs pages use the same style sheet. Let’s see how it looks on docs pages. To my experience, the gap between image and text is rather too big than too small.

And I don’t think we should shrink the images. It is important to see everything well at first sight.

What I forgot in my last comment. Maybe, you should just refer to the Fedora registration. As far as I know, it is an indispensable prerequisite.

1 Like

That is already on my list. At the moment, I just included the images as they are, which implies their original size, so that I have something to put forward for feedback. They definitely need to be shrinked!

Good idea! I’ll put that on the list.

We’ll see if this is possible, this will depend on where/how we present the HowTo.

I think we should not shrink them too much, too keep everything visible as good as possible. But I think that decreasing the size a bit makes sense. At the moment, it is a bit like “monster images” with some tiny text in between.

I’m not sure if I know what you mean. I mentioned the GitLab account as primary login instance because this is the easiest way (default by the Docs web interface) and some have GitLab already (I tested it, to put forward MR you do not need the Fedora Account System). I also mentioned the Fedora Account System login (including the link) as alternative for those who want to use it, but if someone has a Fedora account in advance, I assumed it is not necessary to elaborate how to use the FAS. Anyway, using the FAS for our Docs GitLab increases complexity and the number of steps, so I choose to not focus this method for “sporadic contributors” - of course we can discuss and change that. Absolutely necessary is FAS only for those who accept/approve the MR, which is the permanent Docs team. If someone has not yet a FAS account, I think a GitLab acc makes more sense for now anyway. Or did you mean something else?



But before I start to do formatting and such, it might be clarified how (which is linked to where) we present the HowTo: do we make a PDF to which it can be linked? Shall it stay an md file as it is at the moment? Or do we make it itself a Docs file with AsciiDoc? Originally, I intended it to be a PDF (out of habit, and this seems to be something everyone is used to : ), but now that you brought up the idea of integrating it into Docs, I am open to that, too. That question should be considered before starting to do formatting :slight_smile:

It would be a lot of work, but I wonder if short gif animations showing each “transition” would be better than the static images? I think a “demo” might be even easier for people to follow than a document. With the document format as it is, people have to read each bit of text and then do a little “where’s waldo/wally” search in the picture for the artifact that is described in the text. If instead, you could make a series of animations that showed the mouse pointer moving from somewhere around the center of the screen to the item, clicking on it, and also how the page is supposed to transform/transition to the next state/step, I think that might be slightly easier for the reader to follow and a little more informative. You’d still have some short text below each step explaining what is going on. But, potentially, someone could watch the series of animations and figure out how it is supposed to work without even reading the text.

Just an idea.

I’m not sure. Personally, I do not like using such animations as I often work in a different speed than HowTo animations, so I have to wait for the animation, or vice versa. For some the animation might be too slow, for others maybe too fast, some need different speeds at different tasks. With static pictures everyone can determine the speed themselves and focus on each task / read as long as they want. Also, some texts cannot be replaced by animations (such as the information that branches can be ignored; or the two login possibilities). But my perception is not necessarily representative, so we can discuss that!

My perception is that the blue buttons catch your eye directly, this is why I did not highlight them additionally. To achieve the same for the “fork” button and the history/edit/ticket buttons, I marked the first with a red arrow and the latter with a red circle. Do you think we should emphasize artifacts more, including the blue buttons?

I have just created a PDF draft that already incorporates slightly shrinked images with borders as suggested by @computersavvy . If we decide to use a md / asciidoc file, I can prepare that, too.

@jbley If I understand you correct, you have not yet worked with Git: do you think that we can remove some images? I am thinking if we can “compress” the HowTo a bit, but I don’t want to lose clarity for people without git experience.

Personally, I guess the picture after “Then, search the change/update within the Docs page you have now opened in the Web IDE and …” and before “… make the change/update you want to suggest:” can be removed? The next picture is more or less the same I think.



The pdf draft is here:

1 Like

That’s cool. I’m not even sure if I would like it. It was just a thought.

I think consistency is import here. At least with the way my brain seems to work, I have a much easier time finding something when I have the exact image I’m looking for in my memory. If for example, the directions say to click on the orangish squiggly thing that kind of looks like a colander, I will have to expend much more mental energy hunting for that in the image than I would if I knew that I was looking for the same sort of red circle that was used in the previous image. FWIW, I think the red circle works well and I’d recommend using that consistently.

1 Like

Makes sense.

I’ll include red circles throughout all images in the next draft. :+1:


Supplement: both drafts are updated with red arrows throughout all images

1 Like

Is access request not required to work on a repository?
Is the workflow different for the Developer in the Fedora Docs GitLab subgroup?

Additional/specific access rights are not necessary to make a merge request. You can use any GitLab account and any FAS account to make MR. But you need to have additional access rights to approve/accept a MR.

When externals follow the HowTo, they fork the repository from Fedora Docs so that they have that repo in their own GitLab account. Thus, they can change whatever they want but it will remain on their forked repo in their own account. It will not touch the “central” Fedora Docs repo until a developer accepts the MR.

As a developer, you can directly accept your own merge request. I have not yet tested it, but I guess that a developer can also skip the MR and commit directly to the respective branch, without forking in advance.

1 Like

2 posts were split to a new topic: Fedora Docs GitLab for developers

Being really honest, I have to agree with this comment about that:

The process is a 7-step process which not only includes creating a new account, learning/knowing a markup language to edit in plain text in an IDE, making a fork, commit and merge request (which would would be alien concepts to someone who is not a programmer), and then follow the MR flow.

It’s too much complexity for someone who won’t dedicate their time to it, we need as little friction as possible to the process.

Ideally, it should be a simple 3-step process:

  1. Click the edit button
  2. Edit the page with option to preview the results
  3. Send for review

Basically, IMHO, to edit something on the documentation it should be as easy as editing Wikipedia (or any other wiki) anonymously, just with GitLab being used under-the-hood.

For example:

  • The contributor shouldn’t have to create their own account, just use a generic “fedora-project-docs-guest” account and somehow associate the MR to their FAS.
  • The contributor shouldn’t have to fork, edit via WebIDE, then create a commit and a MR, just give them an WYSIWYG editor, a “Reason” field and a “Send for review” button, those are used to generate the MR.
  • The contributor shouldn’t have to figure all the complexity of using the GitLab web interface, they should have an tool as simple as possible to their needs for editing and dealing with the review process.

To sum it up, GitLab will work for any person that already knows how to use it or is willing to learn, but for anyone else they need a simple tool.
We just need to have GitLab as the “advanced” mode and figure out how to create an “basic” mode.

3 Likes

I guess that would be “doable”. But I think someone would have to write a custom javascript-based editor specifically for the Fedora project’s documentation. I just google’d the concept, and it looks like such js editors do exist.

Maybe someone could fork the above project and strip the interface down to just a “Send for review” button?

BTW: There is an online demo of sorts here (The link in the readme seems to be broken).

1 Like