Ideas and collaboration for Quick Docs

Continuing the discussion from Writing Workshop Schedule:

I’m taking a liberty of creating a new thread with the subject that matches the topic. @hamrheadcorvette thanks for sharing ideas.

The vast majority of Quick Docs articles works for frequently used activities like adding repo, system update, which are not affected by release cycle. However, part of the content gets outdated according to release notes and a change to upstream projects.

Maintenance of documentation is equally important as well as creating new sections of articles.

I’d intentionally :slight_smile: stop commenting about how to solve contributor’s pathways and the scope of Quick Docs, so folks in various working groups/SIGs can join our effort to maintain docs.


@boredsquirrel based on your recent Docs-related topics/posts, this could be interesting for you :wink:

1 Like

I don’t want to take this out of context, so could you elaborate more on this ?

What I meant was I wanted to give other folks opportunity to comment on and I wait for a few days until I give you my take-on. Make sense?


Very true! I am becoming a part of the Linux community without even knowing any real programming language XD


Scope and definition

I realized the scope of Quick Docs appear nowhere in the contributor guide and README page of the repo itself. An article on the Fedora Community Blog in 2019 provides a definition and how it started.

Pull requests

From my experience, I would create small PRs per each article and change on a topic. You can manage this by creating a feature branch to your fork. I don’t believe there is a need for multiple forks.

Also best practice on PRs tells us about making small PRs that fulfill a single purpose.

1 Like

The beauty of all this, is that you don’t need to know a programming language to engage in a computing community. You bring what you can, All of this is wide enough to cover many walks of life and all are welcome ! That’s the beauty of Community based projects.

  1. Grammatical corrections

From my experience, I take a couple of articles that I have fair knowledge about and then

  • read them through for first review
  • run them through spell checker (preferably built-in checker in text editor) and linter like Vale CLI locally
  • commit small changes and create pull request per each article

I don’t think there is a need to discuss your changes about stylistic improvements in advance.

  1. New articles
  1. Process/step improvements

You’re editing for technical accuracy and completeness.

Take note of guides that skip sequences of actions and are not descriptive enough for users to follow through to complete process

  1. Translations

From my point of view, you can pick up-to-date articles that are not affected by release cycle and help translating them.

Check this workflow documentation: Documentation Translation Workflow :: Fedora Docs

  1. Archiving of deprecated articles (Outdated information)

It is worth checking with maintainer or board members of the Docs repo about archiving and deprecation process.

  1. Types of content

There are two types of articles in Quick Docs - How-to-guides and Tutorials.

Tutorials could be longer than how-to-guides.

Please let us know which articles are hard to read and needs reviewing for conciseness and freshness (up to date).

  1. “I’d like a better understanding of the people involved and the process”.

Documentation Writers

UX designer and Docs Infra


Welcome to :fedora: Discourse ! :hugs:

For me, finding Go-To persons is a godsend to any obstacles I faced along contributor journey.
Go-To persons are not necessarily technical reviewers or maintainer. For example,

  • if pipeline failed on a pull request: find who can help
  • if merge conflict happened
  • build script throws out error
  • when I don’t know what to do with new article ideas
  • the moment I hit obstacles

Matrix Chat is the best place to know people casually as well as discussing documentation bugs and technical issues. There is no way to have contributor guide for all of obstacles we might face.

1 Like

I do 90% my collaboration on the phone. Weblate is somewhat usable (even though I am totally confused how to find the correct pages of interest) but Gitlab… or even Git at all.


Localization team will be able to assist you with workflow. Some of working groups use voice/video call feature of the Matrix chat. Docs team also uses it when required like Docs workshop.


Hiya, on another note, I feel quickly drained if I work like a lone writer with zero interactions and go radio silence. Collaborative writing goes a long way.

If you want to go fast, go alone; if you want to go far, go together.


I would like to mention a topic I made yesterday:

I do have a proposal for the docs-team about Quick Docs. The mentioned above had in my opinion, missing/confusing information.

The missing information/example was to restrict size and or cleaning older entries with journalctl. And as a bit confusing I find the “foo” variables commonly used in documentations. In a quick doc, I think it would be great to use “real world” examples. This would make them more readable, and also would be more for users where not have a tech. or programming background.

I wanted to know if we in the ask.fp.o section could agree for a tag, where we could mark quickdocs where need some adjustments ? Not to to tell you, that you would have to change them, more as a mark for new members of the doc-team that they could pick some ask.fp.o cases if they want to try to do something on their own. Or if you need material for the workshops you make for the new members of the team.

I was thinking on something like #quickdoc-edit or so ? What do you think. Would this make sense for a kind of collaboration in between the ask team and the docs-team?

If someone complains about a missing documentation we will invite them to help with creating the missing content. Being more transparent with the whole workflow, to create good docs/quick docs.

1 Like

Hiya, many thanks for taking time to offer suggestions.

We got to face the fact that articles get outdated and leff unattended and not maintained. That’s why we also call it docs bugs.

Some articles have admonition or header paragraph clearly indicating ‘this article is out of date’. Others may not have that warning at all. I would jump in to update the paragraph containing outdated information (meaning pull requests) if I spotted something that I know very well.

You could also report the issue in Quick Docs repo directly using the magic button on the top right corner of the page.

  • ‘Edit this page’ - middle button
  • ‘Report an issue’ - last button


To be fair, I would disagree with an idea to create another tag in discussion as I have seen lots of suggestions to create all sorts of tags and it is hard to find necessary ones. That is sort of additional layers of efforts, asking people to put another tag.

1 Like

Let me share my take-on that, I do believe, chimes in with your idea. Check the article about content reuse I wrote recently to bridge super-helpers Q&A forum and reviewers. I’m in discussion on the Matrix Chat Docs room.


Never mind then … I just will tag them as howto. If needed I mention/link the quick doc and everyone can feel free to cherry pick.

I did try going thru the process of documentation. It is unfortunately not for me (personal and time reasons).

I will do that about the “foo” mentioned in the quick doc. Issue #743: [main] Doc issue in file modules/ROOT/pages/viewing-logs.adoc - quick-docs -

I was thinking on that, when I proposed the tag. But i guess now you are well served with the howto + guide tags.

1 Like

:100: I feel the same way.

1 Like

Existing tags like howto or guide will work. :slight_smile: I’m quite familiar with it.

Ask Fedora and Docs are already connected in many ways by cross-referencing solutions in Quick Docs and labelling ‘common issues’ in Ask Fedora.

My aim is to lower burden of super helpers in Ask Fedora and get more done by users self-help.

That’s fine. The idea is not to persuade helpers to go through Docs process and write articles. You already help users a great deal. You don’t have to feel obliged to write articles in Quick Docs.

But please understand it is not entirely Docs team’s role to write, review and maintain Docs. The work has to be spread across various working groups and one-time contributors as well as external contributors (we have some).