Informal meeting at Flock is scheduled on 2024-08-09T18:00:00Z→2024-08-09T19:55:00Z to discuss onboarding new comers, barriers, improvements planned but on backlog, and organizational improvements.
Thank you @hankuoffroad for compiling this list! Maybe we can look at opening up a Google Meet or some video session during the Flock session. I know this will be a late time for the Europeans and Asians though.
What docs would you like to see in the official Fedora Docs?
Installation and Configuration
Infrastructure Docs (either refering to upstream docs or docs when upstream does not exist)
Common Issues that are unique to Fedora linux
Docs for tools that are unque to the Fedora platform (perhaps these exist in upstream already or in CentOS…)
Limiting the scope of Fedora Docs is important so that we don’t create docs that are unmanagable to keep updated and edited.
What obsticles do you find as a possible contributor to docs?
Fragmentation of multiple Git forges makes finding the documentation you desire to fix or add to difficult. (Could unify all Fedora Docs under one name space if Fedora adopts a new Git forge, but this could be months away.)
Complex Current pipeline: To make significant changes or additions to Fedora Docs it is important to create a local editing environment and use a git work flow. Since our sources are in a variety of Git forges.
Quality bar is set high (probably more a reference to the “Current onramp” mentioned below)
Current onramp is difficult for new contributors in light of above mentioned obsticles. Current onramp requires: creating FAS account, learning git, finding correct Git forge and namespace for the docs contributor is interested in, uploading ssh public key (ssh urls are often easier to work with when submitting edits from a local editing environment), forking, creating branch, making edit, making PR.
Current pipeline shortcomings:
a. Not easy to download locally a full set of the documentation so that links between documentation can be checked.
b. Not easy to get a local display of the final .adoc pages that you create. As an example, sometimes the stylesheets in a repo are outdated and don’t display as the final rendured document will display on docs.fedoraproject.org.
c. There is not an automatic series of checks that will evaluate .adoc files to find: broken links, syntax errors, and other errors that could perhaps be automated.
What would help attract new Fedora Docs contributors?
Create a gentle onramp for a new contributor.
a. (Possible idea): Encourage new contributor to write documentation addition or edit on discussion.fedoraproject.org and then tagged with a special tag so it is noticed by Fedora Docs team and reviewed for inclusion.
b. Tagged Documentation could either be added by member of Fedora Docs Team or…
c. (Possible idea) Fedora Docs Team member mentors new contributor through steps of pipeline and this doc becomes their first contribution.
Unify all official Fedora Docs under one namespace in one Git forge
Create an easy way to report typos or outdated docs or broken links to the Fedora Docs Team (like a simple form or button on docs.fedoraproject.org that notifies Fedora Docs Team of a documentation issue) This would make it easy for someone to become a contributor who reviews the current documentation for possible errors and edits.
What role would a centralized Fedora Docs Team fulfill?
First keeping in mind that our current team is very small and could use additional active contributors.
a. Manage source repos for official Fedora docs.
b. Look for opportunities to include contributions to discussion.fedoraproject.org into docs.fedoraproject.org
c. Consolidate docs repos to make sources for docs easier to discover.
d. Unify stylesheets used in all docs repos for local previews.
e. Work with other groups within Fedora that maintain documentation and encourage them to make fixes to outdated or broken documentation inside the repos that they maintain.
The above summarizes a number of discussions that happened during the Birds of a Feather session from everyone that came to contribute to the discussion. About half of the room had edited docs in the past and the other half were curious how they could contribute in the future.
I sincerely appreciate your input to coordinate discussions and capture detail. I’m pretty sure we need time to get feedback after Flock/summer holiday season.
Hopefully, we could schedule a video call in September to discuss what happens from here.
I just noticed today that there is documentation for “bootc” which is a very new project at least I hadn’t heard anything about it until Flock. The documentation is in our Gitlab instance, and seems rather complete, but originally forked from CoreOS.
I bring this up because perhaps the process for bringing the “bootc” documentation into the Fedora Docs could reveal some practices that the Fedora Docs team could adopt. Questions that could be explored:
It doesn’t appear as if a member of the Fedora Docs Team was involved with the inclusion of bootc documentation into the Fedora Docs, so what is the current process in deciding what gets included in Fedora Docs?
It appears as if the docs were brought into our Gitlab instance by forking some docs from CoreOS (which I think, their docs in Github for Fedora CoreOS). Could their process of starting the bootc documentation and the process of bringing it into Gitlab be used to centralize all of our docs into one Git Forge so the team would not have to clone multiple git repos from multiple git forges to make edits?
Since the Fedora Docs Team doesn’t appear to be involved, who maintains these docs now that they are a part of Fedora Docs, who decides when these docs are outdated or no longer relevant?
How are decisions made in the exposure of these docs within the Fedora Project? (I found them through a link from the Fedora Podcast, are there other ways these are easily discovered?)
Just some food for thought, which might further help determine future steps for a Fedora Docs Team.
Being a (small) contributor to the bootc and Fedora CoreOS docs, I’ll try to answer some of the questions from my perspective.
That is correct. The bootc docs have been forked from the CoreOS docs repo on GitHub.
With the move to a new Git Forge, this could possibly happen, at least to some extent. Personally, cloning multiple git repos from multiple git forges is not a issue for me.
The main maintainers of these docs are the developers involved in these projects and that’s why they are very rarely (if ever) outdated or no longer relevant. This applies to bootc, CoreOS, Atomic Desktops and possibly IoT.
I think it would be helpful to have a link to them on the main Fedora Docs page.
Recommended practice is to use built-in Antora search (Lunr Extension), rather than navigating through general navigational bar on top right and link to pages by each edition.
Blue buttons block on the Docs page is already crowded. Adding more and more repositories there would look even more crammed.
Thanks @hricky for your thoughts and clarifications.
Thanks @hankuoffroad for the clarifications. I agree with you that the main Fedora Docs page is probably cluttered enough, and I’m glad to see that the search seems to do a good job of exposing documentation when it exists. I noticed the main search box on docs.fedoraproject.org gives you the same results. If our media outlets like Fedora Podcast and Fedora Magazine continue to make efforts to include links to docs.fedoraproject.org those would be good ways to expose new documentation for projects.
I added the original questions to stimulate thoughts about the role a Fedora Docs Team in the Fedora Project as a whole. It is wonderful when the teams who are developing a portion of the Fedora Project also creating the docs and have the ownership and maintainership of the documentation. They are the best equipped to fulfill those roles in keeping the documentation updated. Perhaps, the role of the Fedora Docs Team would be to investigate when or if a portion of documentation has been orphaned. Orphaned documentation could then undergo a process similar to how Fedora deals with orphaned packages, and this process could be carried out by a Fedora Docs Team.
As the Discussion at Flock shed a light on the issue of pipeline/automated check, there are known limitations around Docs QA and consistency of quality checks by different writers.
a. Build and preview script docsbuilder.sh creates the fully rendered site on your machine to preview your changes before making a pull request to the Fedora content repositories. However, there is no link validation on the script. In GItLab CI, pipeline check broken links. See the latest video tutorial on link checking.
b. local preview: I updated the guide. Please let me know if we can improve it.
@mowest Many thanks for stepping up to run this BoF at the last minute and for taking detailed notes.
This makes me wonder. Wikipedia has a classifier on wiki pages as good articles or excellent articles. This is a method that highlights pages that are well-written and well-maintained. Because the Fedora Docs are so decentralized and spread out, what if came up with a “Top Picks” of the Fedora Docs? This would be a trusted collection that encourages newcomer contributions across multiple domains. The important factor would be that the repo is actively maintained and there are multiple reviewers. This increases the likelihood that a new contributor is able to successfully contribute to the Docs.
Eventually, they may become more confident and approach a docs site or repo that is a lower quality, and help improve that one.
I am curious, did any of the existing Fedora Docs pages on the process come up during the hackfest? Were they already known? If yes, could the pages be improved somehow?
I like the idea of a “mentored contribution,” or identifying some small, researchable tasks for a repo that a new contributor can work on together with a mentor. In a way, it is like pre-assigning a mentor to a ticket.
I’m not sure how feasible this is though.
I admire this idea but I feel like this introduces a lot of complexity. There are 68 unique repositories built into the Fedora Docs site today. Merging 68 repositories into one repository would be mildly chaotic and difficult to maintain. Or this my hypothesis, anyways.
Perhaps we could consider more accessible interfaces for accepting feedback. The two immediate options are Google Forms and LimeSurvey, which are not exactly built for this purpose in mind. It would be nice to have some kind of public web form that hooked into a special Discourse tag for the Docs team. This would make all feedback up for discussion and follow-up by members of the team.
@mattdm Do you know of any tool we could use that might hook into Discourse like that?
While it is true that we do want to strengthen the core, central Docs Team, I also believe part of the secret of the success of the Docs Team is leaning into our decentralized approach more. I think we need to empower more people to become good stewards and maintainers of Fedora Docs. And hopefully some of that empowerment translates back into involvement with the core Docs Team.
This was my activation story for Fedora Docs, in many ways.
Could the idea of a trusted collection like I described above work here?
I would love to have a simplified build pipeline where anyone could pull a container locally, attach a volume of the local directory and other git repos to build as dependencies, and assemble it together.
Something like this:
podman run --rm -v .:/docs:Z -it fedora-antora:latest ./docsbuilder.sh
I wonder if we could do a better job of providing CI config files for various platforms and providers, e.g. GitLab CI, GitHub Actions, Pagure CI/Jenkins, etc. If we could provide a more robust way for any team to sanity check their documentation using the pull request workflow and easily get a public preview of the site, I believe this would be a valuable investment of time by the Fedora Docs team.
The GitLab CI config that I tend to use does build a local preview, but it is partially broken because the web server does not follow paths to an index.html file, like how our site is built. Links in the document might point to docs.fp.o/my-team/welcome/ but only docs.fp.o/my-team/welcome/index.html will load the page. It would be nice to fix this for a better user experience.
Maybe it could be an Outreachy intern project in 2025?
How about something simple like pre-commit to start with? It could do basic checks—broken links, linting, syntax checking and so on?
“As I type linting” requires people to set up their IDEs, I don’t know of a way around that. Perhaps our builder script could grow a few linting steps too (but then folks do still need to use our script).
I saw this recently and wanted to share it as dont think commit hooks are the answer for linting. CI is almost always better and cant be bypassed as easily as just adding --no-verify to your git commit command. I think it also has a strong potential to frustrate contributors as hooks often prevent people from committing, which may break workflows for contributors that prefer to hack on things and make frequent commits, and then run a linter and commit all the linter changes at the end.
As an alternative, I believe it would be preferable to explain the contribution requirements (i.e. linted code following a particular standard) in the repo’s README/CONTRIBUTING file, and then provide instructions for people to configure their IDE’s and workflows to lint on save, or whatever they prefer (and if thats hooks, so be it, but we shouldnt configure this for them)
So, it’s not just for linting, it’s pre-CI checks. For example, it’s common practice in Python projects to set up pre-commit to run flake, mypy, and other checks. What this ensures is that these are run before one commits, so one can make immediate fixes rather than wait for CI to catch them and fail.
This does not replace CI, it adds to it.
(CI can also be easily bypassed anyway—most CI platforms support [skip ci] etc. )
I didn’t see the video, but if they’re making blanket statements like “stop using pre-commit and only rely on CI”, I clearly disagree with them
I am in favor of scheduling a video call or Matrix meeting to layout a road map of tasks with priorities. There has been a lot of feedback in this thread already, giving us more than enough to fill an agenda for a meeting.
And I agree with those docs. Only one of the four you linked even mentions any kind of hooks (the gitlab one), and thats talking about pre-push hooks, which im slightly more okay with than pre-commit hooks. I would argue that pre-push may still get in the way, for example if a contributor is pushing to their own fork of a repo to mess around.
My problem is with the hooks, not with the existence of linting and running automated checks on the code. I dislike how hooks effectively allow maintainers to reach into a contributors PC and (in very many cases) attempt to impose restrictions on or otherwise control what happens there with respect to the particular codebase.
Maintainers obviously are allowed to dictate what style guidelines their codebases follow, but i would argue this should be enforced at the time a contribution is actually made (i.e. when a PR is submitted for example). That way the linter remains a tool for “if you want to contribute to this codebase, you must follow our rules”, rather than “if you use or modify our code in any way, even locally or for a fork, you must follow our linter rules”.
I would be fine with hooks if they did not block me from being able to do what i want with the code on my computer (i.e. make commits or push as often as i want) and simply gave a warning like “hey your code isnt passing this linter check. If you plan to contribute to you should fix this before you make your PR so it doesnt fail the linter in CI”
Sounds good. My timezone is UTC+1 (UK). I’m available between 18:00-21:00 UTC on Fridays after work.
If that works for you, I’ll be opening a poll here.
I understand the sentiment here, but in all the discussions here, the assumption has been that the code/docs will be contributed back to the repo.
If one does not want to contribute code back to the repo, they can go ahead and disable any linters/hooks/etc. completely. A simple way of not invoking pre-commit hooks is to use --no-verify with git commit:
-n
--[no-]verify
By default, the pre-commit and commit-msg hooks are run. When any of --no-verify or -n is given, these are bypassed. See also githooks[5].
One can always create a new branch, disable all hooks and play with it all they want. Then, when they are reaady to contribute code back upstream, they can enable the hooks again, clean up their commits (as is suggested), and then push the code for review?
Edit:
For the pre-commit tool specifically, one has to explicitly run pre-commit install to activate the pre-commit hooks, and one can later run pre-commit uninstall to uninstall them. The latter will then not require one to use --no-verify etc.
