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.
Yes, I would love to. Which sub-topics do you want me to expand under ācontributor guideā?
I didnāt know other options to contribute to Docs other than a complete authoring environment using Git and Podman / Docker. Iām happy to take a challenge.
The topic you suggested resonates quite well with me.
A large portion of my day job is about knowledge base, consolidation of user documentation or writing memos for project team about self-service guide. I think it is a good fit for my experience.
I presume this needs to be team effort rather than individual SBC enthusiasts who happen to be the Fedora contributor at Docs/ARM SIG and moved away from the Raspi.
i suggest if SBCs other than the Raspi need to be tested by Docs authors/ARM SIG, we would need loan samples to play with. Is it something the Fedora council can support?
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.
with proprietary boot firmware = without Fedora at all
So we have:
Advanced interface for fast I/O and industrial use case: like PCIe / SATA
4 gb min
min real 1 gb ethernet (not slowed down by insufficiont internal bus)
text console (not just a real serial terminal)
Stackable (all permanent connectors (power, eth, ā¦) on one side, all temporary connectors (e.g. USB) on opposite side, no connector, switch, etc anywhere else)
To name a few we discussed. I currently know just one model that fits: Pine64 RockPro 3399.
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.
Is it okay to write on this route? Working with large document on local folder will be beneficial, so I can work offline for hours (on and off) and render it with Antora, and commit.
What Iāve done is;
Click āCloneā button
Run VS Code ssh inside WebIDE
Clone repository to a local folder
Open readme file in VS Code (all too familiar with this)
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.
Fair enough. Iāll walk through other options that are close to the wiki page you published.
Download artifacts and edit the document using any text editor/AsciidocFX
Setting up an authoring environment
one additional option (WebIDE): Please shout if I did something wrong by forking a project or the WebIDE didnāt behave as you expected. Iāll clean up the fork.
It warns me;
Youāre not allowed to make changes to this project directly. A fork of this project has been created that you can make changes in, so you can submit a merge request.
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.
