Steps suggest find a document to update those that start with //FIXME in nav.adoc file.
There is nothing I can do with the ones inside //FIXME
Steps need to include a situation where there are other files that require updating, instead.
Rewrite Steps: There are seven steps, but in new and occasional contributors’ perspectives, the sequence and descriptions need to be rewritten. I presume the biggest barrier to new contributors to Doc workflow that they are assumed to know various tools (ascii, git workflow in Pagure and Podman) with no learning curve. These are obvious for most users in the Fedora workgroups, but not always is the case.
If pre-requisite knowledge is essential, we need to mention this upfront.
Installation - Fedora on Raspberry Pi (Installing Fedora on a Raspberry Pi using the Fedora ARM installer)
– This Quick Doc misses lots of steps.
To differentiate it from server doc (full configuration), Quick Docs for R Pi needs to be succinct and self-contained on its own rather than cross-referencing to numerous Docs.
I want to support the quick sprint task as above. I wonder if it matches goals of Docs WG. Please advise.
I fully agree with your analysis of the instructions in the document. The current publishing process is made by developers for developers. Authors have completely different processes. They are more likely to be discouraged. And developers are known to be mostly not enthusiastic documentation writers.
I have written a slightly different tutorial for Server: Server/Documentation/How To Contribute - Fedora Project Wiki
There is also (both in Pagure and in GitLab) the option to edit the file directly. This is not included in the instructions and would probably be the easier option for occasional contributors. And on all pages there is now a corresponding link.
And there is an additional issue that the ARM SIG has its own version on its wiki pages, which seems to be largely the same. And the biggest problem is that Fedora Workstation is actually unusable on a Raspi 4 due to the lack of graphics support. And the linked long list of “supported” boards is silent about the fact that in most cases the support is highly incomplete.
Instead of a text about the Raspi, there needs to be a text about SBCs as a whole, and a note about which boards are at all suitable over a graphical Fedora desktop. A positive example might be the Pine64 Rockchip Pro boards.
We have talked several times about Quick Docs needing improvement.
This concerns especially its structure. There are many items that are only applicable for Workstation, but not for any of the other editions. But that is not explicitly said. Perhaps one would have to make an outline not according to system components but according to editions. Or show this explicitly and immediately recognizable for each article. Maybe you could get involved in such a more extensive action, too (not alone, but in cooperation)?
But also the improvement of single articles would be very helpful. And maybe a tutorial on how to create articles using the direct edit function.
Ultimately, of course, it depends on your interests. But from a Fedora Docs POV, I think we should start with a low barrier contribution path - as we agreed upon previously. That means either single file editing or WebIDE.
Maybe, WebIDE is the first choice. My impression is that this is not much more time-consuming or difficult than editing a single file. But it offers many more options.
Yes, on the other hand, the basic structure of installation and administration is the same for all models.
There seem to be some options. But first we would need to develop criteria for which of the vast numbers of SBCs are eligible. As far as the Server Working Group is concerned, we have been wanting to compile a list of criteria and, based on that, a reference list of suitable and supported models for some time. But we don’t have anyone at the moment who is determined to push this forward. All active people are busy with other things.
All the docs pages are at gitlab now, also our docs team page and current contributors guide.
There is a WebIDE button beyond the green line on the right half.
But some docs of various editions and spins are still in pagure. We may have to describe pagure as well. But let’s first focus on GitLab, I think. There is all the docs content we want to find new contributors for.
Re. contributor guide, I think it is ‘good first issues’ to start with.
I suggest two parts.
Documentation is valuable and easier than you think: This paragraph needs to state why we prioritize documentation. We need to show some practical examples to back them up. I would need your input as empirical evidence (pain point, anecdotes, data …), if possible.
Documentation provides provenance for release cycle, for users and QA team
Documentation pays for itself with the time it saves in the long run for users and Ask Fedora contributors
Documentation can be streamlined to work side by side with release cycle, so it shouldn’t be a stand-alone task
Documentation helps self-disciplined users get on with Fedora projects
Above points are taken (adapted/reworded) from a book ‘Effective Computation in physics’ - Field guide to research with Python.
A quote below from the book holds true for a source of my interest and passion.
New users need either documentation or hand-holding, but hand-holding does not scale.
Procedure: I’m doing sort of UAT for new contributors.
GitLab WebIDE: user settings (request access to sub groups, add ssh/GPG key)
However, WebIDE in Documentation Contributors Guide does not allow direct edit. It has to be forked or cloned. See below message when I clicked WebIDE.
But I wouldn’t tie all of our documentation so tightly to releases. The changes are too small. Ultimately, this depends primarily on our resources, how quickly we can adapt documentation to changes in a release.
As I understood it, you don’t need a local git at all. You may have to make a fork, but that is done at gitlab, not locally.
I think, you have to write a new workflow “webIDE/Antora”, i.e. how to use webIDE to work on a Antora document
That just an issue if you work with a local git/Antorra working environment. In any case you have to clone the repository. If you are the main maintainer of the document, you must not fork, but commit immediately to the repository. All other authors will create a fork as well and commit to the fork. And the “main maintainer” will check and merge it into the repo.
Well, I think so. But, I’d like to keep away from the current war for the domination of the developer desktop. And also from the infiltration strategy of forming commercial alliances between tech companies under the guise of open source efforts. But unfortunately, at least many Fedora developers are not much smarter than the average uneducated Joe Doe Internet user in this regard.
We should make a strict effort to present the factual options available for a content contribution and describe the corresponding workflows - and alternative paths within a framework, if available and useful.
Maybe we should start by describing the essence of each procedure - at maximum three accurate sentences each. And then a table comparing the 3 approaches, their advantages and disadvantages. That would then be a decision-making aid.
I think to be able to clearly demonstrate this, we need our own staging platform as soon as possible.
Forking a repo, then opening a Merge Request is the recommended workflow for most contributors. You did nothing wrong
You can’t make edit directly on the upstream project unless you’re part of the docs-team.
I uploaded a rough-cut storyboard for ‘Create documentation using Web IDE.’
here HackMD link.
Before I create merge request, could you advise if there is anything out of norm?
Just to be sure accident-proof (this will be my first commit, so nervous) and run through end to end before I improve the content.