There are some dark corners in the current Guidelines documents, which haven't been looked at in years. Some pages now contain outdated, irrelevant, or incorrect information.
As part of the migration of the official "Packaging Guidelines" from the Wiki to the new docs site, we should evaluate the state of each page - including its correctness and currentness, before removing the old content on the wiki and replacing it with a "this has been moved" banner.
We also discussed adding a "last-reviewed" metadata tag (or something with an equivalent name) as an AsciiDoc document attribute, to indicate when a specific page was last reviewed for correctness - to make it easier to look for outdated information in the future.
Might as well turn this into a general place to track what we need for the wiki deprecation.
I agree that we should have some metadata indicating when one of us last actually checked a document for correctness. Certainly we can just look at the last commit date, but... a typo fix doesn't indicate a readthrough. :last-reviewed: works fine for this; just include it immediately after the title (first line of the document, which starts with a single equals sign). We can trivially grep out the unreviewed or stale pages. Please, let's use ISO dates.
:last-reviewed:
I see no reason to indicate who did the review, as you can get that from git. The only reason to include it is if we wanted to indicate somewhere on the page when it was last reviewed and who did it, but I don't think we do.
Once a document is reviewed, we should get the content out of the wiki somehow. We have two options:
Both are trivial. The latter has the disadvantage that it is difficult to get to the page history. You have to append ?action=history or you get instantly redirected. Personally I don't much mind but I'd like to see other opinions.
?action=history
In the meantime I will be continuing the cleanup. I have recently found that the Naming guideline page was badly damaged in the conversion, so I'll be working on that.
Here's a list of documents which need work after the wiki conversion. Please edit this list as you find or fix broken pages.
Very many pages have no titles; to fix this, add the page title on the first line of the document prefixed by an equals sign and a space. Metadata goes after that, and the content starts after the first blank line. Add :toc: immediately after the title to add the table of contents (which sadly is not currently styled at all).
:toc:
Metadata Update from @tibbs: - Issue priority set to: In Committee (was: Needs Review) - Issue tagged with: meeting
We talked about this in today's meeting (https://meetbot-raw.fedoraproject.org/fedora-meeting-1/2019-02-28/fpc.2019-02-28-17.01.txt):
Should we ask docs team to put redirects in place?
There doesn't seem to be any need to ask the docs team to do this; we can do that ourselves trivially. See the current https://fedoraproject.org/wiki/Packaging:Python page (which you can't even see unless you visit https://fedoraproject.org/wiki/Packaging:Python?action=edit).
I suppose we don't need to discuss anything here, removing a meeting tag. We just need to go and finish redirects.
Metadata Update from @ignatenkobrain: - Issue untagged with: meeting
Login to comment on this ticket.