3 ms·
The article touches upon an important point that applies to all complex (software/computer) and long-lived systems: "Too much outdated and inconsistent document
by c0l0 1y ago
The article touches upon an important point that applies to all complex (software/computer) and long-lived systems: "Too much outdated and inconsistent documentation (that makes learning the numerous tools needlessly hard.)"
The Debian Wiki is a great resource for many topics, but as with all documentation for very long-running projects - at least those that do big, "finished" releases from time to time - it seems tough to strike a balance between completeness and (temporal) relevance. Sure, in some weird edge case scenario, it might be helpful to know how this-and-that behaved or could be worked around in Debian 6 "Squeeze" in 2014, but information like that piling up also makes the article on the this-and-that subject VERY tedious to sift through if you are only interested in what's recent and relevant to Debian 12 "Bookworm" in 2025.
Most people contributing to documentation efforts (me included) seem very reluctant to throw out existing content in a wiki article, even though an argument could be made that the presence is sometimes objectively unhelpful for solving today's problems.
Maybe it would be worth a shot to fork the wiki (by copying all content and have a debian.wiki.org/6/ prefix for all things Squeeze, a /7/ for Wheey, a /12/ for bookworm, etc.) for each major release and encourage people to edit and extend release-specific pages with appropriate information, so readers and editors would have to "time-travel" through the project (anmd problem/solution) history in a more conscious and hopefully less confusing way, and make it easier for editors to prune information that's not just relevant for release N+1 any more.
I'm very open to learning more about anyone's thoughts on how to solve this well: How to keep documentation in "living documents", editable not only by a small group of contributors (like many projects to with mkdocs et al. as a replacement for an actual wiki), but also keep the "historic baggage" both easily discoverable (for when it's relevant and useful, because that does happen), yet not have it stand in the way of all those who will be confused and obstructed by its presence.
- hereonout2 1y agoAre you acquainted with the new maintainers guide rather than the wiki? To be honest I found it an incredibly comprehensive overview of Debian packaging, all the way up to using pbuilder to ensure dependencies and sandboxed builds, onto lintian to assess the quality of the artifacts. https://www.debian.org/doc/manuals/maint-guide/ https://www.debian.org/doc/manuals/maint-guide/ Building complex Debian packages is time consuming with a lot to learn, but to be honest I don't remember having many issues with this guide when I started out.
- danesparza 1y agoYou are only making the original author's point for him even more. I didn't even know this guide existed, for example -- because of all the existing noise that exists in the same space. I have managed to build Debian packages (and even self-host a repository) IN SPITE of the existing documentation, not because of it.
- hereonout2 1y agoThat's not the experience I had. The guide I linked to used to be linked to from the main docs page I believe - I went to double check and it now has this more recent guide linked instead - it seems equally thorough. https://www.debian.org/doc/manuals/debmake-doc/ https://www.debian.org/doc/manuals/debmake-doc/ These guides were sufficient for me to learn packaging pretty complex Debian projects, and are linked to from the docs home page on the Debian site. Guess that's all I'm saying.
- kmacleod 1y agoI'm building a community site DevOptimize.org: The Art of Packaging[0] for this type of content. Would be glad to host with an interested editor(s). Near-term roadmap includes wiki editing, currently in git. [0] https://devoptimize.org/ https://devoptimize.org/