Re: Culling obsolete pages on wiki.debian.org

Paul Wise <[email protected]> Sat, 20 Aug 2022 12:56:12 +0800
Newsgroups	gmane.linux.debian.devel.www
Organization	Debian
Message-ID	<[email protected]>
[sorry for the long mail, lots of thoughts below]

Dan Coleman wrote:

> One thing, you will need your email whitelisted by someone on this
> list (I don't know who has that authority, but I've seen quick
> turnarounds on requests) before you can make an account.

I set Borden's email address to approval for wiki account registration.

Borden wrote:

> There's the other matter of what to do with pages like
> https://wiki.debian.org/DebianFirewall ,
> https://wiki.debian.org/Firewalls ,
> https://wiki.debian.org/FirewallRules that kinda-sorta talk about
> different things but could also be merged into a single primer for
> newcomers. Is there a 'merge' tag analogous to Wikipedia?

I agree that those three pages are a complete mess and need to be
reorganised. Personally I dislike large pages that conflate several
different but related things into one massive page though. For example,
the page about iptables should definitely be separate to one about
available firewall tools. Adding a merge tag won't achieve anything
though, it will just sit on a TODO list and never get fixed.

Borden wrote:

> I'd be grateful for some guidance on the diplomatic way to remove or
> update obsolete information without offending people.

My approach is to change documentation so that it either will get
automatically updated or won't need people to do manual updates for
inevitable changes. That approach is of course impossible or hard for
every page and consequently every piece of documentation will always
become outdated eventually as various circumstances change over time.
Keeping up with the changes is also hard to impossible because not
every place changes can happen is monitored by a person and not every
person who monitors changes will bother to update every place those
changes affect. There are also many places that changes affect, not
just the Debian wiki; a change might affect Wikipedia, several
different packages, multiple salsa repos and one or two or several
unpackaged GitHub projects. Often a change won't affect an entire
document, just a small part of it and the users of the document will be
able to notice that and work around it locally. Other times the change
doesn't matter that much so updating it is great but it is fine to use
the old version too (for eg http vs https or apt vs apt-get install).
There is also only so much time in the day to dedicate to rewriting
documentation and only so many people willing to do any documentation.

Some current practices on the wiki:

There are zero automatic procedures for changes to the wiki,
every change to the source text of pages is done by a human.

Use WikiTags for changes that need to be made at some point when you do
not have the time to work on it right now. There are zero guarantees
any person will look at these tags/pages though.

https://wiki.debian.org/WikiTag

Add macros for things that can be auto-updated. For eg matching stable
to bullseye is <<DebianCodename(stable)>>, more are needed of course.

Rewrite things in ways that make them last longer.

Updating stuff is preferred over deleting stuff, because an obsolete
document that is partially right still often has more value than no
document at all. Sometimes deleting stuff is the correct answer tho.

Reference externally maintained documentation instead of basically
duplicating that on the wiki, since it will just get outdated.

Pages that will inevitably get outdated but don't necessarily get used
much after they get outdated can be left alone. An example of this are
hardware installation pages, after a few Debian releases the page might
be obsolete but the hardware is also obsolete and so it is unlikely
people will do new installs on it, but it could still happen and the
page will likely be at least partially right after it is outdated.

Pages that only document an old version of a package/procedure, update
them to work with current versions of software in stable.

Pages that have several per-release sections, try to join the sections
up so we don't have to add new sections for new releases, delete the
sections for unsupported releases.

When you edit a page to do a particular change, first do a cleanup of
all the different outdated things, like http/https, apt/apt-get, then
make the actual changes you wanted to do.

Generally we keep pages that are of historical value, for eg Emdebian
on the CategoryObsolete page was a historical Debian derivative that
ended up making lots of valuable changes in Debian itself.
Or pages for old events, those are kept for historical reasons.

Examples of how deep the rabbit hole of updating stuff goes:

https://wiki.debian.org/SuitesAndReposExtension

My current TODO list includes 40 different obsolete URLs.

-- 
bye,
pabs

https://wiki.debian.org/PaulWise
signature.asc (application/pgp-signature, 833 B)