Contributing to docs is very confusing
I found a part of the docs to be rather hard to understand and wanted to propose a change. The contribution process was rather confusing and needed some guessing.
This is my user experience:
- Read the docs on the website
- Click "Edit on GitLab"
- Sign up to Gitlab (using SSO provider for ease of use)
- "Edit" > "Single File only"
- Page reloads, nothing happens (no errors)
- "Edit" > "Open in Web IDE"
- 404: Page not found
¯\(ツ)/¯
- Click on my profile picture for no good reason, but since we are there, set a profile picture, because why not...
- Find two messages: "You need to set up a password to use HTTPS... SSO doesn't work", "you need to add an ssh key to..."
- Set up a password
- Set up an ssh key
- Navigate back to repo / .rst file
- "Edit" > "Single File only"
- Page reloads, nothing happens (no errors)
- "Edit" > "Open in Web IDE"
- 404: Page not found
¯\(ツ)/¯
- Navigate to main page of repo for no good reason, but since we are there, read some things,...
- Find "Please see ... for how to submit changes to QEMU."
- Navigate to "Submitting a Patch" page
- Learn that I need to send patches via E-Mail
- Navigate back to the repo, find about trivial patches
- Learn that there is a process for trivial patches, but only for not actively maintained subsystem. I don't know if this system is actively maintained.
¯\(ツ)/¯
- Spot that .../Contribute/SubmitAPatch and .../Contribute/TrivialPatches have the same path, and navigate to .../Contribute to see if it works (.../Contribute works, .../Contribute/ not)
- Learn that there are scheduled calls ons Tuesdays
- Navigate to Getting started for developers, although I'm not really acting in the capacity of a developer, just want to propose a docs change --> "If you find bugs in the documentation then fix them and send patches to the mailing list. See Contribute/ReportABug."
- Navigate to report a bug --> "QEMU does not use GitLab merge requests; patches are sent to the mailing list according to QEMU’s patch submissions guidelines."
- Confirmed that I need to send an E-Mail, probably via the normal process.
It seems like there is no dedicated process for docs changes. It would be way easier to just go ahead and dump the text into an issue, although it is not a bug, but I do respect procedures and don't want to see the effort rot in the tracker
Proposals for improvements:
- Change "Edit on GitLab" Link to a landing page, which explains that in fact, you can not edit this page on GitLab, but fork it and send the patch via E-Mail
- Create a simple / low barrier path for docs changes
- Enable single file docs changes via GitLab via the "Edit"-button
- Enable and accept single file docs changes via GitHub mirror repo too
- Create a "single file docs changes" mailing list or issue tracker or something like that
Currently, it seems like this is only for people, who *really really* want to contribute and have good intuition for loop-holes.
Would be nice if this process could be (slightly) improved. Qemu is a pice of awesome tech <3