jflory7 commented

Owner

Summary

Compact the "How to Create and Use a Local Fedora Documentation Workflow" article and integrate instructions for running local previews.

Background

This issue is Part 4 of 5 in the Ticket #1 doc overhaul. Right now, information about setting up a local environment and previewing docs locally is spread out. Combining these into one unified, compact guide will drastically reduce the friction for new writers trying to test their changes.

Details

This task comes with full mentorship support! Ping @jflory7, @pboy, or @pbokoc to claim this issue.

To resolve this issue, work on the How to Create and Use a Local Fedora Documentation Workflow article:

Edit the document to describe the basic local workflow in a more compact, digestible way.
Integrate the separate article/instructions on "How to run a local preview" directly into this workflow document.
Ensure the flow from "writing" to "previewing locally" is seamless.

Outcome

A single, easy-to-follow guide that takes a contributor from setting up their local environment to successfully rendering a local preview of their work.

# Summary Compact the ["How to Create and Use a Local Fedora Documentation Workflow" article](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/tools-local-authoring-env/) and integrate instructions for running local previews. # Background This issue is **Part 4 of 5** in the Ticket #1 doc overhaul. Right now, information about setting up a local environment and previewing docs locally is spread out. Combining these into one unified, compact guide will drastically reduce the friction for new writers trying to test their changes. # Details This task comes with full mentorship support! Ping **@jflory7**, **@pboy**, or **@pbokoc** to claim this issue. To resolve this issue, work on the [How to Create and Use a Local Fedora Documentation Workflow](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/tools-local-authoring-env/) article: 1. Edit the document to describe the basic local workflow in a more compact, digestible way. 2. Integrate the separate article/instructions on "How to run a local preview" directly into this workflow document. 3. Ensure the flow from "writing" to "previewing locally" is seamless. # Outcome A single, easy-to-follow guide that takes a contributor from setting up their local environment to successfully rendering a local preview of their work.

jflory7 self-assigned this

2026-02-24 17:38:36 +00:00

pbokoc was assigned by jflory7

2026-02-24 17:38:36 +00:00

pboy was assigned by jflory7

2026-02-24 17:38:36 +00:00

jflory7 added a new dependency

2026-02-24 17:41:03 +00:00

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

jflory7 added the

good first issue

help wanted

labels

2026-02-24 17:54:54 +00:00

egret commented

2026-03-10 10:41:56 +00:00

Member

@jflory7, @pboy and @pbokoc, I'm also quite keen to help with this.

pboy commented

2026-03-10 12:05:31 +00:00

Owner

Eli, that's perfect. We discussed that months ago. And you got a member of the initial initiative team with this project. And I think, you can work together with korora, who is member of the Fedors Server Edition WG and specifically engaged in our Server contribution efforts. I'm taking the liberty of assigning this ticket to both you and korora.

egret added this to the (deleted) project

2026-04-22 08:33:46 +00:00

egret self-assigned this

2026-05-05 12:43:39 +00:00

jflory7 removed their assignment

2026-05-05 13:53:03 +00:00

cstrauf was assigned by jflory7

2026-05-05 13:53:03 +00:00

pboy was unassigned by jflory7

2026-05-05 13:59:06 +00:00

pbokoc was unassigned by jflory7

2026-05-05 13:59:07 +00:00

korora was assigned by jflory7

2026-05-05 13:59:08 +00:00

cstrauf was unassigned by jflory7

2026-05-05 13:59:08 +00:00

jflory7 commented

2026-05-05 14:23:20 +00:00

Author

Owner

Discussed in 2026-05-05 Docs Team meeting.

The consolidated local authoring guide is now ready for review. All Docs Team members are highly encouraged to read the draft and provide their feedback here in the ticket.

Follow-up Items:

Action: @egret and @korora to kick off a Matrix team room discussion about a deadline for this ticket and what is sensible for their individual capacities.

_Discussed in [2026-05-05 Docs Team meeting](https://discussion.fedoraproject.org/t/fedora-docs-team-meeting-2026-05-05-organization-wide-issue-labels-workflow-updates/190491)_. --- The consolidated local authoring guide is now [ready for review](https://forge.fedoraproject.org/egret/team-docs/src/commit/660af29c2442f1dced486d6d45912be54d5069d0/modules/ROOT/pages/contributing-docs/tools-edit-local-clone.adoc). All Docs Team members are highly encouraged to read the draft and provide their feedback here in the ticket. **Follow-up Items:** * **Action:** @egret and @korora to kick off a Matrix team room discussion about a deadline for this ticket and what is sensible for their individual capacities.

jflory7 added this to the 2026 Q2 Team Goals milestone

2026-05-05 14:23:31 +00:00

cstrauf commented

2026-05-05 14:45:46 +00:00

Member

@egret @korora I read the guide at https://forge.fedoraproject.org/egret/team-docs/src/branch/local-docscontrib Well done! :) I have the following comments:

General stuff:
- You're using absolute links a lot. It's probably better to use relative links.
"Prerequisites":
- There's a link to "First steps". However, the target of the link isn't named "First steps". This might cause confusion.
- In the linked "First steps" secion gitlab is mentioned -- does it make sense to update that section too (out of scope for this guide but a general thought)? Maybe at least mention that the "create gitlab account" part can be left out?
- You very thoroughly explain CLI commands how to clone the repo but don't show people how to install git. Might make sense to give them the dnf line how to do it.
- The AsciiDoc-Part should xref the "AsciiDoc for Fedora" page for convenience.
"Edit the AsciiDoc code with a text editor":
- In "Prerequisites" you mention that any editor is fine but in this section you assume that people would always want three windows open (folder structure, terminal at project folder and adoc file content window). I think that this is not actually necessary in general. One window with one adoc file in vi might be perfectly fine. It might help to rephrase this section to not sound too restricting.
"Pushing your changes to your remote fork in Forge":
- There're different opinions on doing git add .. In some circles, it's frowned upon. :) It might make sense to do git status and only add stuff that you actually added or modified. Maybe others can chime in on this topic. :)

The guide is nice and concise. One thing I'd like to see added is a section about podman. The docsbuilder.sh script will leave podman images on you machine. So it makes sense to inform new users that this is the case and also tell them how to clean up these images. Maybe giving the basics (podman ps, podman image ls etc.) would be a good idea.

@egret @korora I read the guide at https://forge.fedoraproject.org/egret/team-docs/src/branch/local-docscontrib Well done! :) I have the following comments: - General stuff: - You're using absolute links a lot. It's probably better to use relative links. - "Prerequisites": - There's a link to "First steps". However, the target of the link isn't named "First steps". This might cause confusion. - In the linked "First steps" secion gitlab is mentioned -- does it make sense to update that section too (out of scope for this guide but a general thought)? Maybe at least mention that the "create gitlab account" part can be left out? - You very thoroughly explain CLI commands how to clone the repo but don't show people how to install git. Might make sense to give them the `dnf` line how to do it. - The AsciiDoc-Part should xref the "AsciiDoc for Fedora" page for convenience. - "Edit the AsciiDoc code with a text editor": - In "Prerequisites" you mention that any editor is fine but in this section you assume that people would always want three windows open (folder structure, terminal at project folder and adoc file content window). I think that this is not actually necessary in general. One window with one adoc file in vi might be perfectly fine. It might help to rephrase this section to not sound too restricting. - "Pushing your changes to your remote fork in Forge": - There're different opinions on doing `git add .`. In some circles, it's frowned upon. :) It might make sense to do `git status` and only add stuff that you actually added or modified. Maybe others can chime in on this topic. :) The guide is nice and concise. One thing I'd like to see added is a section about podman. The docsbuilder.sh script will leave podman images on you machine. So it makes sense to inform new users that this is the case and also tell them how to clean up these images. Maybe giving the basics (`podman ps`, `podman image ls` etc.) would be a good idea.

korora commented

2026-05-14 03:52:11 +00:00

Member

i have pushed your changes, @cstrauf. I have also added a brief section on podman. Only thing I don't know how to do is the xref links. i also broke the numbering on the pushing to remote section, don't know how I did that...

@egret opened a PR for my changes, I think we are close to ready to publish this.

i have pushed your changes, @cstrauf. I have also added a brief section on podman. Only thing I don't know how to do is the xref links. i also broke the numbering on the pushing to remote section, don't know how I did that... @egret opened a PR for my changes, I think we are close to ready to publish this.

egret referenced this issue from docs/team-docs

2026-05-19 13:04:04 +00:00

local-workflow-update #58

pbokoc added the

labels

2026-05-29 12:23:41 +00:00

pbokoc referenced this issue from a commit