Docs meeting agenda: 2022-11-16

Project Discussion
1

Here’s the agenda for the meeting 2022-11-16T19:30:00Z in #fedora-meeting-1:

  • Announcements
  • Action item followup
    • pboy to test run the new builder script on Mac
  • No tickets/MR flagged for the meeting on GitLab:
  • Updates on the new variant-oriented pages
  • Proposal on adding Vale linter (Overview - Vale.sh) to the documentation writer workflow
  • Time to drop old docs?
  • Your topics here!
2 Likes
2

Minutes and full logs are available.

Highlights

We agreed to finally retire the old docs (anything prior to F26). The old documentation website will always be available on Pagure for archival purposes.

Action

  • pboy to test run the new builder script on Mac
  • darknao to deploy WIP workstartion-docs on staging
  • darknao to set up Vale linting on contributors-guide and Fedora Linux homepage repositories
  • darknao to remove old docs from the website
2 Likes
3

Hi all,

I’ve uploaded a snippet to GitLab with my suggestions to revisit local Docs writing environment.
Please let me know your thoughts.

2 Likes
4

I had a quick look through the snippet. A few points came to my mind (but let me know if I’ve misunderstood the work that’s being done):

  1. In Step 1, you mention podman. Is it worth mentioning anything about Docker? (Assuming some folks are using it)
  2. In Step 2, is there a prerequisite to fork a repository in GitLab or Pagure before cloning it to one’s machine? And similarly, when pushing to a remote, should a local branch be pushed to the forked repo before creating a merge request? Should this be mentioned?
  3. In Step 8, you mention build.sh and preview.sh. In the Fedora Docs Template link there is a tool docsbuilder.sh for building the documentation. Is that going to replace build.sh and preview.sh ? Does the docsbuilder.sh command need to be mentioned in other places (such as the guide you’re writing) ?
5

Thanks for you heads-up.

I have re-run the steps just now.
Step 1. Yes, I overlooked Docker. Updated.
Step 2 (moved to 3). I referred to a different page here. Updated my draft including forked repo.
Step 8 (moved to 6). i came across docsbuilder.sh on the other repo only yesterday. I wasn’t sure if that would be a replacement for build.sh and preview.sh. I’ll try.

6

I had a look at the snipped. Unfortunately, we still haven’t a comment function integrated as hackmd.io or etherpad with its chat.

I think we have to be more oriented towards authors and their workflow and sort the individual GIT steps into that. That’s the idea behind the subheadings.

And we should be less technical in our wording.

That, very briefly, as a note.

7

Unfortunately, we still haven’t a comment function integrated as hackmd.io

GitLab snippets have a text field you can comment on underneath. Also you can use version control for snippets there just like Docs.

Screenshot from 2022-11-23 20-31-32

I think we have to be more oriented towards authors and their workflow and sort the individual GIT steps into that. That’s the idea behind the subheadings.

I like that idea. Paragraphs and sub-headings in the GitLab Fedora repos appear succinct and easy to follow through. And close to what you’re referring to.

And we should be less technical in our wording.

Sure, that helps engage with more authors.

8

I’m aware a new builder script ./builder.sh -h is on test, so maybe we need to wait for that.