7-click HowTo for Fedora Docs

Project Discussion
21

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
22

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
23

IMHO, we need that with a WYSIWYG AsciiDoc editor (or at least preview functionality) and then something where the contributor can follow along with the review process.

Edit: Unless the basic version of the review process will be a simple “Accepted” and “Not accepted”, then we don’t need something for that besides an email.

1 Like
24

You don’t want much do you. :slightly_smiling_face: I guess that would be this project then and you’d have to figure out how to merge the two.

(preview link)

1 Like
25

Ok, ok, maybe the WYSIWYG editor is overkill for this right now. Sorry for that! =P

Let’s try to only implement the “Next editor” for now and that should enough for reducing the amount of steps, we can rethink the WYSIWYG editor later.

I am not very good at js, but I could take a look at stripping it of the features we likely won’t need.

(Of note: It seems I can’t use the hosted version of Next editor on Firefox desktop? Seems the ServiceWorker is failing to run) Just saw the edit.

1 Like
26

I think that link is broken. Try this one:

1 Like
27

Just a thought but …

People “volunteer” edits for Fedora Magazine articles with surprising frequency (see here for an example from today). Maybe submitting small edits to Fedora’s documentation could work similar to the way Fedora Magazine’s comments do?

That is, there could be a more-prominent “submit a revision for this page” button at the bottom of each page and the button would open basically two input boxes with two buttons below (similar to making a comment on a Fedora Magazine article). The input boxes would be a one-liner for approved/rejected feedback via email (optional) and then a multi-line text area pre-populated with the asciidoc representation of the page that someone could edit. The two buttons at the end would be submit or cancel.

2 Likes
28

That could work well, we could use that form to edit, the “Submit revision” button would trigger a bot that would create the MR.

That would make it possible to totally skip out needing the standalone git editor, at the price of restricting the basic editing to just a single page (which, IMHO is good, anyone that wanted to edit multiple pages at once wouldn’t use the basic mode).

So, that would make the process:

  1. Contributor clicks edit button
  2. A form opens for editing the current page
  3. Contributor submits edit
  4. A bot specifically created for this takes the edits, generates a commit and MR
  5. MR goes through review process (optionally sending link for MR to user)
  6. When review process is finished, an email is sent back to the contributor with status of review

Then, the WYSIWYG editor could be used with integrations added to work with that bot.

At least, that is how I could see it working for a full “basic” mode.

3 Likes
29

I also agree that git makes it more complex than it should be for external contributors, and although I agree that the point @dalto made applies to many cases (it applies to many security issues I am working with), it does not apply here: we are aware that this is not the best solution for external contributors, but the Docs are not just around external contributors. The “Fedora Docs team” makes up only a part of the Docs. Other teams have to be considered as well, and all contributions have to come together at some point. Think on the work you would create for developers who write related Docs along with developing Fedora, if they had to manage another versioning system along git while both cannot be mapped to each other. I am quite sure this stakeholder group is a critical one, so you have to also consider their interests.

Also, unlike Arch Linux, we have multiple releases plus rawhide/main that have to be managed along with each other (using branches). The community structure/audience can also not be compared (being able to install Arch Linux in a usable way already proves that you know what you are writing when contributing, and the social dynamics usually ensure that contributions come mostly from people of within the respective community).

NEVERTHELESS: I would absolutely appreciate any wysiwyg editor / tool on top of git if it makes the process simpler / shorter for external contributors! I like your ideas, and I would be happy to create a new HowTo for that. I already managed to keep the branches away from externals. So, your editor could directly forward to the respective Docs page’s branch, and we can do the rest (transfer it to other branches if that applies, and so on).

But be aware: your editor has to end up in a merge request, not a direct commit. The latter will cause a lot of indirect issues and I do not think that this will be possible for every potential external contributor.

Unfortunately, web development and javascript ain’t my strengths, so I cannot offer much support here :frowning:

Independent of that, it might be noted that given the experience in our little “case study”, the primary issue seems to be the prejudices about GitLab and git at all, not the GitLab reality: the way we can do external contributions with the current HowTo does not make it necessary to understand branches, MR, or git CLI. The issue is that people anticipate that and thus, don’t get into the topic at all, and the second issue is that several pages have to be passed before the contribution is ready, which feels annoying if someone does not understand why this is the case.

1 Like
30

Ah, I get what you mean. The idea here is to move the complexity away from the contributor so they don’t have to know about it.

Ideally we need two tools that work together:

Frontend: The WYSIWYG editor that integrates with the Edit button on the docs and sends the resulting edits somewhere for we to use
Backend: A bot that receives those edits, creates a commit and a merge request on the repository

2 Likes
31

Yes. Given the feedback and the collaboration with ask.fp, the 7-click HowTo is already usable without preceding knowledge about git.

But it does itself not solve the issue of the prejudices (this is what I want to tackle here, although this discussion does not necessarily need to focus on my 7-click HowTo but also on alternatives, such as an HowTo for your approach), and the number of steps is still more than an external contributor appreciates. And although people do not need to understand MR, branches, forks, … in the 7-click process, the absence of understanding of that can increase the perceived annoyance of the many steps.

So in general, any simplification and reduction of steps through a frontend for external contributions would be very cool!

In your example, the bot would also need to create a fork at the start of editing, to then create a commit and then a merge request. Maybe it would make sense to create a dedicated account for the bot? However, this would of course also mean that everyone can use the edit button without affiliating the edit with a specific (FAS or GitLab) user. Another issue is to maintain such a tool, including frontend and backend: if applied to the Fedora Docs pages, we need to rely on it.

Supplement: When further elaborating a dedicated frontend/backend/tool for external contributors, it might makes sense to open a new thread for that :slight_smile:

32

The issue isn’t prejudices. The process is legitimately vastly more complicated than it should be for casual contribution. This is from my perspective as someone who uses git on a daily basis. It isn’t about something that feels hard but really isn’t.

There wouldn’t need a fork to be created since the tooling could have appropriate rights to create a branch. It could all be done transparently to the user if that is something that makes sense to pursue.

33

Yup, I came up with that earlier, when the goal was to remove the need to create an account to simplify the process, see here:

Of course, the “someway to associate the MR to the FAS” thing I thought of was having a way to connect the frontend to the FAS system.

34

May I ask what brings you to the conclusion that your point is more applicable than the case with @computersavvy and the discussion around? He had no Git(Lab) experience before, but summed up himself this. I am not sure if your conclusion is representative given the development of the discussion and the little exchange we had at the ask.fp lounge, including @computersavvy 's feedback.

We already agreed that the GitLab way ain’t perfect for external contributors, but again, there are other interests as well.

I am aware of the technical possibility. But I would not grant “developer” access to a bot which has not passed massive testing/review in this function while it is used (and at the worst exploited) by any external contributor we do not know in advance. This can be dangerous. Would you take the responsibility for that? And develop/tailor and maintain it? You should not forget that the capabilities of the Docs team are limited. We have not that much personnel, and the issues that may rise with that could paralyse us for long.

1 Like
35

An alternative is to incorporate the SAML link to do a normal FAS login: SAML single sign-on for Fedora · GitLab (this link uses the FAS account and automatically logs into GitLab with it, no separate GitLab account)

In this case, people are automatically forwarded to a login they already know, and we have a user we can associate the contribution to. However, it assumes that all contributors are Fedora members, although I guess we can assume that the vast majority will be.

I didn’t focus on that because it would have increased the number of steps. But if you create something dedicated anyway, it might make sense to focus on it.

36

I believe this applies here:

The two methods can co-exist, the existing one is the advanced mode, the to-be-created one will be the basic one.

IMHO, we shouldn’t require the contributor to do too much learning for what should be effectively a once-and-done contribution, they will likely give up.

1 Like
37

I never stated that my opinion was more applicable than someone else’s. However, @computersavvy is a single person. I have never said or implied that there is nobody who is willing to contribute if the docs use a standard git approach.

That has no real material bearing on if process is simple or complicated for a casual contributor. I don’t even comprehend how anyone who has actually been a part of contributing to documentation on other distros would consider that process “simple”. There is nothing simple about it.

I think you are making this more complicated than it actually is. There doesn’t even really need to a “bot”. Just an application that can access git. I think the risk is pretty low.

That being said, I am not saying that this should or shouldn’t be done, just that there is no purpose in maintaining tons of forks for system generated MRs.

38

I think the idea is that if there is a dedicated account, then there would only need to be one fork (of each project) for that account. The biggest problem is probably that it loses the ID of the contributor if all the MRs come from that one account.

39

That seems reasonable. It is essentially the same thing. The application would still need to be able to create branches in that fork for each MR.

Since the idea is that it is transparent to the submitter, that shouldn’t be a huge hurdle. Whatever tool that maintains the link between the request and MR could maintain the contact information.

40

My point was that, although Jeff was the sole one who already passed the whole process in a practical case, there was feedback from other people without previous git knowledge, and for me it looks subjectively a bit like going towards a consensus that people without previous git/developer knowledge find the graphical 7-step process comprehensible (if complemented by a HowTo) and understand how to use it, but there seems to be also a consensus that this process should be shorter and more intuitive for them. We already elaborated the reason for the latter, and for now, I think the first consensus has to be sufficient because we will not be able to get rid of git. Even developing a dedicated frontend would take some time (if it even proves feasible technically, organizationally and by personnel).

So I don’t see a tendency to a rigid “git” = “developers only”, but just a “it could be more intuitive for non-developers but it works”. Also, our graphical 7 steps for editing are not comparable to a “standard git” approach. Feel free to review it.

Previously in the thread it was called bot, but feel free to designate it application. The outcome remains widely the same: someone needs to develop and maintain it, and I don’t think that you will find the Docs team to take the responsibility for giving such an application “developer” access, and this type of access is what is necessary to achieve what you imply.

Also, what you imply in order to avoid forks leads to direct commits, a problem elaborated before. You are finally replacing much that GitLab provides and so you have to re-develop it: no fork → direct commit → when to do review/approval? If the application makes itself a direct commit, it has to incorporate the review/approval process, and this will create another system next to the GitLab we would have to get used to. Personally, I don’t think there will be support for that. I would like to again remind that there are other interest groups as well.

@dalto @mateusrodcosta @glb
Generally, I see much work to design, implement and then test + ensure long-term maintenance of such an application/frontend/backend, and so on, before it can be deployed - and it has to consider much and be aligned with many processes and stakeholders! Please open a new thread because much organization will be necessary already in advance: you have to talk to several people to ensure that what you want to design & develop can be deployed in this environment, identify other interests/processes you have to consider, and ensure that responsible people will allow the type of access you want. Consideration of using a dedicated account, or FAS accounts, and so on. Also, be aware that avoiding forks (having each fork once, one per FAS account, …) has a lot of implications, plus the issues of loosing the contributor ID in some approaches, … … lots of questions before you can finish a solution + implement it.

Personally, I think that everything that goes beyond a web interface (may it be with FAS accounts or a dedicated one) that incorporates “edit of a branch” + “automatically fork if necessary” + “commit locally” + “make MR” is not realistic given the overall environment. Even that is something I am not convinced that it gets implemented+maintained in a persistently reliable way without creating more work than it solves. But if you want to do that, or even go some steps further, this defnitely needs a dedicated thread in which you can start to organize and evaluate feasibility :slight_smile:

This thread was intended to focus on creating the easiest possible HowTo for the graphical process we already have.