[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
Attachment:
signature.asc
Description: This is a digitally signed message part