7-click HowTo for Fedora Docs

Project Discussion
#1

I have drafted a Quick HowTo (how to edit a Docs page with 7 clicks) that aims to lower the entry barrier to contributing to Docs, with a focus on sporadic contributors outside the Docs team. This HowTo is based upon the experiences gathered/summed in this thread (thanks again to the Ask.fp regulars/leaders for your incentives!). The HowTo also aims a bit to tackle some of the issues mentioned in the not using git thread.

More precisely, the HowTo aims to…
… make clear to potential contributors that this is a graphical browser-based workflow that does NOT need knowledge about about git or merge requests,
… make clear to potential contributors that it is NOT necessary to know the structures of the git repositories of Fedora Docs,
… make clear to potential contributors that it is NOT necessary to search/identify the related repository before a contribution can be done,
… make clear that this does not take much time: in the end, it is 7 clicks plus writing some text, and
… you cannot break anything, so do not worry!

These are widely the (imho false) presumptions I collected from people who have a lot of valuable Fedora and Linux knowledge (enabling them to offer valuable Docs contributions) but who have not yet worked deeply with the Docs or with git.

The draft is not yet formatted (including the images), and the texts are yet very rough as well, but it is something to start a discussion about (updated 20220720):

PDF draft (updated 20220720):

Currently, I think it makes sense to remove the image 5-webIDE.png and to merge the text below and above this image.

One big issue remains that cannot be solved by such a HowTo itself:
In the conversations I had about this, I came to the conclusion that the false presumptions make people assume in advance that this would be too much work or too time intensive, so that many do not even look for/in a HowTo. Obviously, the best HowTo cannot make a difference if no one looks inside this HowTo.

Therefore, it might makes sense to put this HowTo in place at a point where people are directly made aware of it, and it has to appear in a way that makes some points clear: it is easy and fast to edit a Docs page! An “image” button cannot fulfill this purpose. Maybe a “text” button with a corresponding “HowTo: 7-clicks to an edit” text next to the existing buttons makes sense? This makes the potential contributor aware of it fully passively (so that no active action is necessary: not even to put the cursor on an image until some “edit the page” text appears or so). Also, it might make sense to remove the “History” button at all?

Feel free to discuss or to challenge my approach!

4 Likes
Preparing the Docs meeting: Discussing how to integrate the HowTo
#2

While documentation and howto’s are helpful, it doesn’t actually make the process any easier.

In fact, it demonstrates how complicated the process really is.

A process that requires 15 screenshots and text to document cannot be considered “simple”.

1 Like
#3

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
#4

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
#5

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
#6

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
#7

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
Preparing the Docs meeting: Discussing how to integrate the HowTo
#8

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
Preparing the Docs meeting: Discussing how to integrate the HowTo
#9

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
#10

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
#11

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.

#12

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:

Preparing the Docs meeting: Discussing how to integrate the HowTo
#13

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.

#14

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?

#15

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
#16

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
#17

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
#18

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

#19

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
Fedora Docs GitLab for developers
#20

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