Writing workshop 2024 planning (draft)

Hi all, Happy and strong 2024! As we step into the new year, it’s a time of reflection and anticipation.

I’d love to share some reflection and ideas about documentation workshop across a wider group.

Docs workshop post in Magazine in Aug 2023
Community Blog post in Dec 2023

Reflection of Docs workshop in 2023

  • Follow-up with attendees after the event is difficult.

  • We need to get results from Lime Survey carried out in December 2023. (@jflory7 can you help?) [Edit: received, thanks. Responses seem helpful. We will continue post-event survey.]

  • Continue post-event survey all year round, so viewers of recording can share feedback.

Change of video conference tool

Follow up with attendees are easier with Fedora Matrix room than JItsi public instance. We can use Jitsi in Matrix with little introduction for all Matrix users (Element client to use built-in Jitsi widget).

Target audience

  • You use Free and Open Source software run on Linux desktop and/or server to get the job done

  • You love to document tools, features, and how-to guides, which require care and maintenance to ensure technical accuracy and conformance to documentation style guide

  • You are interested in Docs toolchain

2024 workshop topics: if there are suggestions from LimeSurvey, we will review them.

  • Create new articles

  • Working with multiple repos: Example (Writing Docs with Kate - Fedora Magazine)

  • How to test docs

  • Review process: Good review and bad review

  • Code-rich documents: convention and code comments (mainly Bash commands and scripts)

  • Release notes: 2 to 3 sessions

Presenters and co-host

One presenter (main host) per workshop to keep consistency in a session. Co-host is welcome to help out presenter and attendees.

Note: We will wait for LimeSurvey results and more feedback from Fedora community by 2024-01-16T00:00:00Z

If you want to volunteer for a main presenter of a workshop topic, discuss about repo/document pages and scenario in advance with the organizer - Hank Lee.

1 Like

Hi all,

Following up with updates about the Docs workshop in 2024,

  • Time
    Workshop will be held on the last Thursday of each month at 1200 UTC (Jan, Mar, May, Jul) and 1900 UTC (Feb, Apr, Jun, Aug).

  • How to join Element/Matrix Video call

  1. Go to Fedora Documentation Room
    Room link: https://chat.fedoraproject.org/#/room/#docs:fedoraproject.org

You’ll need a Matrix network account to join the workshop live and to interact with host and participants.

If you don’t already have an account you can create one via Element’s Create Account page. Element offers free desktop or mobile apps to join the workshop. Element also offers a web app that allows you to join from your browser.

  1. Click green Join Conference button on Jitsi widget. See image down below.

Workshop host/moderator will toggle video call option on before the workshop.

1 Like

is this on Fedora Calendar?

January/February workshop is updated.

Writing workshop Jan 25 - Onboading


Advanced techniques for editing and contributing to Fedora Docs - Feb 22 by Justin Flory



If someone wants to participate with many of Fedora’s teams and the community, the best experience is to sign up for a Matrix account with a Fedora account. This automatically adds someone into the Fedora space, where they can find all the Fedora chat rooms:

I have a conflict so I can’t make that one, but I hope to hear how it goes!

1 Like

There are Matrix.org users in Documentation chat room, so I thought we don’t need to limit users of fedota.im.

I made some changes to curriculum.

  • Onboarding: how we work session with too much screen sharing (2023), Q&A focused interactive session (2024)
  • Demo and writing session: presentation was too long. Writing session cut short and not followed upon (2023), keep 40-minutes writing session (2024)
  • Tool: web browser only (2023), Git forge agnostic process (2024)

I had to send it out for audiences early.

I include 12 UTC for people in Asia Pacific time zones.

It is not required and anyone can use a Matrix account from any homeserver. However, if someone intends to participate with many Fedora teams and the broader community, and also does not yet have an account, the best way to go is with a Fedora homeserver account because it automatically adds you as a member to the Fedora space on Matrix.

I’m with you on that. I rephrased it with the following. WDYT?

  1. Go to Fedora Documentation Room
    Room link: https://chat.fedoraproject.org/#/room/#docs:fedoraproject.org

Fedora Documentation Room is open to a Matrix account from any homeserver.

If you are new to the Fedora Project and don’t have a Matrix account, we recommend you to create a Fedora Account and connect it with Matrix Account for best experience. Using a Matrix account with Fedora space (Fedora Chat) will make navigation of Fedora rooms easier and help access to Fedora tools such as Pagure (Git forge), Weblate (Translation), Fedocal (team calendar), and Discourse (discussion forum).

Fedora Account: link

Fedora Chat: link

Click ‘Continue with your Fedora Account’

Element offers free desktop or mobile apps to join the workshop. Element also offers a web app that allows you to join from your browser.

[Edited Jan 10]

Agenda (draft)

Please leave your comments if you want to take a part as a main presenter or moderator.

Topic Time Main presenter Recording
Onboarding 1200-1230 UTC Jan 25 Hank Lee No
Advanced techniques for editing and contributing to Fedora Docs 2000-2100 UTC Feb 22 Justin Flory Yes
Onboarding Mar Looking for a moderator No
Working on multiple repos Apr Hank Lee Yes
Onboarding May Looking for a moderator No
How to test documentation Jun Looking for a main presenter Yes
Onboarding July Looking for a moderator No
What makes good review? Break away from a lone writer Aug Looking for a main presenter and co-host Yes

Note) If you’re sharing screen as presenter, join meeting using a Matrix-Element web app from Chromium/Chrome browser.

Hi guys, I’m back after some challenges at the start of the year. Three questions:

  1. Regarding onboarding, so far we were a team of two (Hank and I), which went very well and we were able to gain experience so that the events got better and better. Should things be different now?

  2. With regard to “advanced techniques …”, is there a content plan for this? Will it be compatible with our contributor documentation? Or should we update the documentation?

  3. Regarding “How to test …” What do you mean by test here? On the tool side, we have local preview (still in need of improvement) and possibly vale. Anything else in the quiver?

1 Like

Hi Peter, glad you’re back! :pray: :pray: :palms_up_together:

My idea about changes is;

  • I believe one presenter (main host) per workshop can keep consistency in a session. Co-host is welcome to help out presenter and attendees. So there is no change really. I put down my name for January and April. You are more than welcome to accompany me.

  • February workshop: Justin volunteered for this topic. Also I’m sure it is a good idea to rotate presenters, so people get fresh perspectives and skills. I’d love to learn from him and sit in passenger seat, not driver seat :slight_smile:

  • Test documentation: I mean a basic quality control stuff before one pushes changes to main branch or remote fork for PR review. No, there are no new tools I consider. Local preview script, spell checker and style guide (whether Vale or other method to ensure style guide is met), that’s it.

Check the latest scheduler that supersedes this draft.

I shared this on Matrix as well, but sharing the speaker outline for today’s workshop here too:

  1. Introduction:

    1. About presenter.
    2. Overview of the purpose of the workshop, what will be covered, and what will not be covered.
    3. Quick introduction of all the tools needed to follow along “at home.”
  2. Topic 1: Working from the CLI

    1. Detail 1: Navigating the terminal, installing pre-requisites, setting up a “writer environment”, git feature branching workflow
    2. Detail 2: Editing content and working with AsciiDoc
    3. Detail 3: Previewing changes before proposing them (i.e. container builds, AsciiDoc browser extension)
  3. Topic 2: Pagure workflow

    1. Detail 1: Pushing a feature branch to Pagure, opening a Pull Request, leaving a review.
  4. Topic 3: GitLab workflow

    1. Detail 1: Pushing a feature branch to GitLab, opening a Merge Request, leaving a review.
  5. Topic 4: Adding a new Fedora Docs site

    1. Detail 1: Introduction to the docs-fp-o builder repository and how the Fedora Docs site gets built.
    2. Detail 2: Making changes to Antora configuration file to add a new docs repository.
  6. Conclusion:

    1. Brief overview of what was covered in the workshop.
    2. Where to find links and resources.
    3. Q&A, time allowing.

Thanks for sharing. Much better readable as the image preview on Matrix. By the way, I’m still wondering how to join the Video session. Looking forward.

Sorry, I got this after the workshop. I had to enable Jitsi Widget in Docs Matrix room 1 minute before the start. Thanks for finding it naturally :slight_smile:

1 Like

@py0xc3 Could you help with closing this old thread? Thank you!


Absolutely :wink:

1 Like