Contribute to Quick Docs

@pboy as a follow-up from docs_office_hours.2022-06-09, I have some suggestions to help improve Quick Docs.

  1. Help lowering entry barrier to new and occasional contributors
    Contribute to Quick Docs:

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.

  1. 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.

Let’s discuss this further!

That’s precise and helpful.

Re. articles on other editions, I’ll digest its structure/contents and discuss this in weekly Matrix meeting.

@hankuoffroad Could you imagine to author or co-author an expanded contributors guide? (see my post about improving team page)

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.

That sounds very encouraging and promising.

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.

Do you mean ‘Edit this page’ and ‘Fork and edit’ in Pagure? I’ll play with it just to be familiar with UI and think about the content.

When will the document in Pagure be migrated to GitLab? I just wanted this to be future-proven.

Screenshot from 2022-06-17 21-28-52

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.

1 Like

Okay. It sounds like a long haul project, but I’m interested in discussion on such criteria.

  • Libre software support: With or without proprietary boot firmware
  • Advanced interface for fast I/O and industrial use case: like PCIe / SATA

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.

1 Like

Re. contributor guide, I think it is ‘good first issues’ to start with.

I suggest two parts.

  1. 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.

  1. 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.

Questions

  1. (Just in case I’ve done something stupid) Do I have to set up git locally first before I click WebIDE?
  2. In case WebIDE is not supported for some reasons, can I rewrite git/Antora workflow?
  3. What’s your recommended workflow - git fork or git clone?

Good statement to start with. :slight_smile:

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.

1 Like

I may have gone off track in gitlab webIDE.

Looking at the latest article on webIDE, gitlab appears to promote VS Code integration with webIDE.

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;

  1. Click ‘Clone’ button
  2. Run VS Code ssh inside WebIDE
  3. Clone repository to a local folder
  4. Open readme file in VS Code (all too familiar with this)

Screenshot from 2022-06-21 21-28-46

Screenshot from 2022-06-21 21-47-21

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.

1 Like

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.

1 Like

I think, @darknao is the only one of us who knows about it.

Maybe would be a good idea to set up a mock repo for you to experiment and test your procedures? In program documentation, we regularly do that.

@darknao, what do you think?

Forking a repo, then opening a Merge Request is the recommended workflow for most contributors. You did nothing wrong :slight_smile:
You can’t make edit directly on the upstream project unless you’re part of the docs-team.

1 Like