#225 Documentation issues for Workstation contributors
Closed: Fixed 7 months ago by aday. Opened a year ago by aday.

Look around the usual Fedora "how do I contribute?" resources, and workstation is either missing or the information is out of date:

Fixing links and adding the workstation in various places should be a fairly straightforward task.

There is a wider question about the experience of contributors wanting to get involved, and the fact that there seems to be three separate sites (the wiki, the docs site, and whatcanido), none of which seem to be in great shape, is a cause for concern there. Perhaps that's worth a separate conversation.


In the Server WG meeting, we are discussing the fact that Workstation, Server, and Cloud Edition don't appear on the docs page AT ALL. Somewhat noted in the ticket description but this seems like a pretty severe oversight (I can say I have never noticed before). We should file that this be fixed.

I was thinking that we should move our pages to docs.fedoraproject.org, but the more I look at it, the less enthusiastic I feel. That site does not look good, and from what I can tell, it hasn't been touched for several years. At the same time, all the old wiki pages continue to sit around, driving traffic and causing misinformation, and there's no effort to clean them up.

Internal project information feels quite broken in Fedora at the moment. :disappointed:

Still not especially enthusiastic about docs.fedoraproject.org, but having looked at it again, it's probably still worth doing. Rough proposal is therefore to:

  1. Copy any current material from the Workstation wiki pages to a new workstation project under fedora-docs
  2. Redirect from the current main Workstation page to the new Workstation home page on docs.fedoraproject.org
  3. Somehow deal with historical material that's left on the wiki (probably just leave it in place, with a clear label to say that it's obsolete)
  4. Fix the old links in other Fedora project pages to point to the new Workstation WG home page

https://pagure.io/fedora-workstation/workstation-docs now exists and includes an initial draft of workstation pages to go in docs.fedoraproject.org.

Since there's no easy way to preview the pages, I've requested that they be added to docs.fedoraproject.org. That way the group can review them via the website.

Once we're satisfied with the pages, we can deal with the old wiki pages and update links to the working group to point to the right place.

Workstation docs are now online here: https://docs.fedoraproject.org/en-US/workstation-working-group/main/

It would be good for the group to review the content before I go about changing all the links to point to the new home page.

Metadata Update from @aday:
- Issue tagged with: meeting

a year ago

I went through the WWG docs and I really like them. Thank you Allan for working on this!

Feedback:

  • The meeting time is not right: https://docs.fedoraproject.org/en-US/workstation-working-group/main/#_meetings. The page says 13:30 UTC, but this is only true during US DST. When DST ends, the meeting shifts to 14:30 UTC.
  • The mailing list address has a misplaced hyphen: desktop@lists.fedora-project.org when it should be desktop@lists.fedoraproject.org
  • For chat, it would probably be more future-proof to point to #workstation:fedoraproject.org since Matrix will soon be the primary way to access Fedora chat channels. Doesn't matter too much either way, though, since it's bridged.

P.S. having the wiki pages redirect to the new documentation would be ideal, as otherwise people will assume the wiki is still current.

The meeting time is not right: https://docs.fedoraproject.org/en-US/workstation-working-group/main/#_meetings. The page sasy 13:30 UTC, but this is only true during US DST. When DST ends, the meeting shifts to 14:30 UTC.

The time is pegged to US Eastern?

For chat, it would probably be more future-proof to point to #workstation:fedoraproject.org ...

How does one link to the Workstation Matrix channel? I couldn't figure it out.

The meeting time is not right: https://docs.fedoraproject.org/en-US/workstation-working-group/main/#_meetings. The page sasy 13:30 UTC, but this is only true during US DST. When DST ends, the meeting shifts to 14:30 UTC.

The time is pegged to US Eastern?

Yes.

For chat, it would probably be more future-proof to point to #workstation:fedoraproject.org ...

How does one link to the Workstation Matrix channel? I couldn't figure it out.

https://matrix.to/#/#workstation:fedoraproject.org

Feedback:

  • The meeting time is not right: https://docs.fedoraproject.org/en-US/workstation-working-group/main/#_meetings. The page says 13:30 UTC, but this is only true during US DST. When DST ends, the meeting shifts to 14:30 UTC.
  • The mailing list address has a misplaced hyphen: desktop@lists.fedora-project.org when it should be desktop@lists.fedoraproject.org
  • For chat, it would probably be more future-proof to point to #workstation:fedoraproject.org since Matrix will soon be the primary way to access Fedora chat channels. Doesn't matter too much either way, though, since it's bridged.

Fixed in the source. Not sure how long it takes for the site to update.

P.S. having the wiki pages redirect to the new documentation would be ideal, as otherwise people will assume the wiki is still current.

I was planning on keeping the wiki pages, with:

  • duplicate/misleading material removed
  • a warning banner to say they're out of date
  • a link to the new pages

Mostly because there are quite a lot of old sub-pages which I didn't want to orphan, which someone might theoretically want to use one day.

Currently waiting on https://pagure.io/fedora-infrastructure/issue/10243 so we have a stable URL to the home page. Once that's done we can start updating links to point to the new docs.

As mentioned during today's meeting, the new docs pages include a new mission statement and list of roles and responsibilities for the working group. I think that it would be good for us to discuss in more detail.

It would be helpful to identify what we consider to be mission critical responsibilities, as opposed to nice to haves. It would also be good to map specific activities to each responsibility.

We discussed this last week - removing the meeting tag.

Metadata Update from @aday:
- Issue untagged with: meeting

a year ago

The link to the new docs pages is now fixed and will be stable at https://docs.fedoraproject.org/en-US/workstation-working-group/ . Next step is to update links to point to the new page.

Other tasks

  • The engineering teams page would benefit from some structure (core functions/official editions/spins/special interest, etc)

I got most of this fixed, and the outstanding issues are difficult to resolve with the current overall state of Fedora's documentation.

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

7 months ago

Login to comment on this ticket.

Metadata