docs/tickets
20
4
Issues 31 Pull requests Projects Activity

Improvement of the instructions for the Fedora Local Authoring System. #1

New issue
Open
opened 2026-01-27 10:27:40 +00:00 by pboy · 7 comments
pboy commented 2026-01-27 10:27:40 +00:00
Owner
Copy link

The first step is to analyze the current instructions and draw up a plan for improvement.
Improvement ideas so far

  • More compact/shorter wording
  • Division into basic instructions and reference for specific tasks
The first step is to analyze the current instructions and draw up a plan for improvement. Improvement ideas so far - More compact/shorter wording - Division into basic instructions and reference for specific tasks
pboy added this to the (deleted) project 2026-01-27 10:27:54 +00:00
theprogram commented 2026-02-10 13:51:30 +00:00
Member
Copy link

I believe the current instructions are at https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/tools-local-authoring-env/

I believe the current instructions are at https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/tools-local-authoring-env/
pboy commented 2026-02-24 12:12:50 +00:00
Author
Owner
Copy link

As a first approach I propose the following work packages:

Introductory page

  • Update the tools section to focus on local authoring, leaving the other in the text, but marking as „not current“
  • Update explaining how to get a page from the icons on the documentation.

Article "Create a new documentation module"

  • Update focusing on Local authoring
  • leaving the other parts in place with a warning "outdated"

Contributing to Quick Docs

  • Update with focus on Local authoring
  • Special Focus on Correct Meta Data

Artikel: How to Create and Use a Local Fedora Documentation Workflow

  • Update to describe in a compact way the basic workflow
  • Integrate Artikel (How to run a local preview

New: Article „Git for Writers“

As a first approach I propose the following work packages: ## [Introductory page](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/) * Update the tools section to focus on local authoring, leaving the other in the text, but marking as „not current“ * Update explaining how to get a page from the icons on the documentation. ## [Article "Create a new documentation module"](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/contrib-new-documentation/) * Update focusing on Local authoring * leaving the other parts in place with a warning "outdated" ## [Contributing to Quick Docs](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/contrib-quickdocs/) * Update with focus on Local authoring * Special Focus on Correct Meta Data ## [Artikel: How to Create and Use a Local Fedora Documentation Workflow](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/tools-local-authoring-env/) * Update to describe in a compact way the basic workflow * Integrate Artikel (How to run a local preview ## New: Article „Git for Writers“ * Starting with adjusting and improve „[A Git cheat sheet For Server Documentation Authors](https://docs.fedoraproject.org/en-US/server-working-group/usr-docs-maintenance/gitcheatsheet-for-authors/)“
korora commented 2026-02-24 15:13:31 +00:00
Member
Copy link

I'm going to take a stab at the 'how to create and use a local documentation workflow' portion of this ticket. Since a lot of folks new to Fedora may not have extensive experience with the command line, perhaps something that is available in a GUI form with instructions might also be helpful. A lot of folks seem to be... hesitant to use the command line.

I'm going to take a stab at the 'how to create and use a local documentation workflow' portion of this ticket. Since a lot of folks new to Fedora may not have extensive experience with the command line, perhaps something that is available in a GUI form with instructions might also be helpful. A lot of folks seem to be... hesitant to use the command line.
❤️ 1
jflory7 commented 2026-02-24 15:35:59 +00:00
Owner
Copy link

Discussed in 2026-02-24 Docs Team meeting.

We agreed that the current onboarding threshold for the "contribution machine" is too high for newcomers. To make this actionable, we've decided to break @pboy's proposed work packages into five separate sub-issues. This will allow us to tackle the updates incrementally and flag them as "good first issues" for mentored contributions.

Note: We clarified that GPG signing for commits is not currently supported by our infra and doesn't need to be covered here.

I will be creating the five sub-issues shortly. @cstrauf has kindly offered to help follow along with these sub-issues from a newcomer's perspective! We are also looking for someone to help write a promo post on Fedora Magazine and/or Fedora Discussion once these are up to recruit new writers.

_Discussed in [2026-02-24 Docs Team meeting](https://discussion.fedoraproject.org/t/docs-team-meeting-2026-02-24-simplifying-contributions-and-supporting-new-fedora-users/181834)_. --- We agreed that the current onboarding threshold for the "contribution machine" is too high for newcomers. To make this actionable, we've decided to break @pboy's proposed work packages into five separate sub-issues. This will allow us to tackle the updates incrementally and flag them as "good first issues" for mentored contributions. *Note: We clarified that GPG signing for commits is not currently supported by our infra and doesn't need to be covered here.* I will be creating the five sub-issues shortly. @cstrauf has kindly offered to help follow along with these sub-issues from a newcomer's perspective! We are also looking for someone to help write a promo post on Fedora Magazine and/or Fedora Discussion once these are up to recruit new writers.
cstrauf commented 2026-02-25 05:50:17 +00:00
Member
Copy link

@jflory7 wrote in #1 (comment):

I will be creating the five sub-issues shortly. @cstrauf has kindly offered to help follow along with these sub-issues from a newcomer's perspective! We are also looking for someone to help write a promo post on Fedora Magazine and/or Fedora Discussion once these are up to recruit new writers.

I had a closer look at the current docs and realised that it will take a lot of effort to even understand how everything works and what needs to be done. I need to postpone this effort until @theprogram and I finished the beginner's guide. This issue needs more attention and work than I initially expected.

@jflory7 wrote in https://forge.fedoraproject.org/docs/tickets/issues/1#issuecomment-556773: > I will be creating the five sub-issues shortly. @cstrauf has kindly offered to help follow along with these sub-issues from a newcomer's perspective! We are also looking for someone to help write a promo post on Fedora Magazine and/or Fedora Discussion once these are up to recruit new writers. I had a closer look at the current docs and realised that it will take a lot of effort to even understand how everything works and what needs to be done. I need to postpone this effort until @theprogram and I finished the beginner's guide. This issue needs more attention and work than I initially expected.
korora commented 2026-02-25 16:18:43 +00:00
Member
Copy link

@cstrauf @theprogram If I can assist in any way, please let me know.

@cstrauf @theprogram If I can assist in any way, please let me know.
jflory7 commented 2026-02-26 09:53:36 +00:00
Owner
Copy link

@korora For collaboration on the Beginner's Guide, see Ticket #8.

@korora For collaboration on the Beginner's Guide, see Ticket #8.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels   
Contributors' Guidance
Improve written Material
 Improve the existing contributor documentation

  
Contributors' Guidance
technical support measures
 Improve contributors' guidance by technical efforts like vale or similiar linters

  
effort
high
 Will take a long time

  
effort
low
 Easy fix

  
effort
medium
 Will take some time

  
good first issue
Take this if you're new!

  
help wanted
Needs help or feedback from the wider Fedora community

  
meeting topic
Need to discuss this at a Docs team meeting

  
needs changes
Needs changes or fixes before closing

  
needs reporter feedback
Additional feedback or information from the reporter is needed to advance

  
needs review
Someone needs to look at this

  
priority
high
 Fix this NOW NOW NOW!

  
priority
low
 Low priority tasks

  
priority
medium
 Medium priority tasks

  
priority
on hold
 Work has been temporarily halted, usually because another task needs to be completed first.

  
type/content
Changes to the contents of the site - the actual docs

  
type/misc
Changes to non-content parts of the site. CSS, Actions, scripts, etc.

No labels
Contributors' Guidance
Improve written Material
Contributors' Guidance
technical support measures
effort
high
effort
low
effort
medium
good first issue
help wanted
meeting topic
needs changes
needs reporter feedback
needs review
priority
high
priority
low
priority
medium
priority
on hold
type/content
type/misc
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Improving the Contributor’s Guidance
Assignees
Clear assignees
No assignees
5 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Depends on
#11 Update Introductory Page for Local Authoring
docs/tickets
#12 Revise "Create a new documentation module" Article
docs/tickets
#13 Update "Contributing to Quick Docs"
docs/tickets
#14 Consolidate the Local Workflow Article
docs/tickets
#15 Create a "Git for Writers" Article
docs/tickets
Reference
docs/tickets#1
No description provided.