#518 QD4 Write an author guide for Quick Docs
Closed: moved a year ago by hankuoffroad. Opened a year ago by anthonymcglone.

Based on the discussion https://discussion.fedoraproject.org/t/project-quick-docs-improvement/44322 either

  1. adapt/ "resurrect" an existing author guide to help new (and existing) authors
  2. create a new one (if it doesn't exist)

This includes as a third item an update of the repos README text.

What would we expect included in that guide?

  1. Who can contribute
    • writer
    • reviewer
  2. What type of content
    • how-to (step-by-step instruction to resolve a small problem or task, without extensive explanation)
    • tutorial (step-by-step instruction to use a piece or a set of software for a specific purpose)
    • If it doesn't quite fit below, consider creating a post on a "guide" (typically in Administratin tools box)
  3. How to contribute
    • Pull request workflow
    • either local environment or single page editor
  4. What to pay attention to?
    • Readability (short sentences, structured into short paragraphs. visual guidance / visual structure, no "Pixel Wüste" (pixel desert, don't know the English term for massive, unstructured and therefore just hard to read pile of text)
  5. Not to forget
    • Metadata
    • we want the last 3 authors / reviewers, relevant Fedora release, date of substantial updates (not just spelling)

I think there are common sets of documentation such as workflow organization and style guide Chris and Peter published early this year. Why not refitting them for QuickDocs? This will cover 1, most of 3 and 4. Some of 3 (local environment) has merge request in GitLab waiting for review and approval.

Alternatively, we could use this. https://docs.pagure.org/pagure/usage/pull_requests.html

As I get more acquainted with QuickDocs, I would love to take this. I thought a new contributor perspective might help.

Existing Pagure PR guide is here
https://docs.pagure.org/pagure/usage/pull_requests.html#working-with-pull-requests

Metadata Update from @hankuoffroad:
- Issue assigned to hankuoffroad
- Issue priority set to: needs review (was: awaiting triage)
- Issue tagged with: new change

a year ago

Thanks for taking this.

Some additional ideas:

  1. We should provide a template containing:

    • Title
    • Author names (the last 3 who substantially contributed)
    • Fedora release
    • Last review date
    • Category
    • one or more tags.
    • Abstract (1-3 sentences describing content and goal)
  2. A List of Categories to choose from

    • Administration
    • Installation
    • Managing software
    • Upgrading
  3. A list of Tags to choose from

    3.1 1st level tags:

    • Workstation
    • Silverblue
    • Kinoite
    • Server
    • CoreOS
    • IoT

    3.2 2nd level

    • Problem solving / Troubleshooting
    • Printing / Scanning
    • SELinux

More to come

I can't follow what you're saying with category and tags recently introduced. But I wasn't involved, so I don't really know what to do with it.

Maybe it is good practice to discuss synopsis over next weeks and agree before I take on writing anything. Please bear with me in the life of new contributors who get on with so many things and also frustrated easily.

I can't follow what you're saying with category and tags recently introduced. But I wasn't involved, so I don't really know what to do with it.

Sorry, we discussed that some weeks ago. Antorra includes a system to assign a category to an article and assign one or more "tags". We will give up the navigation tree for Quick Doc. Instead, the Quick Doc startpage contains a list of categories, and you can expand each category to show the list of articles. It is based among others on a redesign proposal of Allan Day, some months ago.

Similar to the categories, you can skim through the existing tags and expand a tag to get a list of related articles. Or you can use the search function to find an answer to your question.

Please bear with me in the life of new contributors who get on with so many things and also frustrated easily.

No worries. I was in exactly that situation a year ago, and I'm still there in some respects. So I know exactly what you are talking about.

And yes, we have to discuss that in greater details, and it is already on our to-do. We discussed that on a previous meeting and decided to continue. I think, as a first step, I'll create a ticket which contains a link to the various discussions about Quick Doc and how to improve it. It dates back to the internship of Anushka Jain at the beginning of last year. Unfortunately, we do not have a register of our meetings. Therefore, it is all quite scattered and difficult to find.

#518 QD4 Write an author guide for Quick Docs will be on backlog until I move on with #521 with consensus to be made with @pboy and a few more contributors. Any comments, please leave them here, not Discussion. Thanks.

Due to backlog in revising #521 and GitLab Web IDE, follow-up on author guide will be delayed.

Metadata Update from @hankuoffroad:
- Issue close_status updated to: moved
- Issue status updated to: Closed (was: Open)

a year ago

Login to comment on this ticket.

Metadata