[arch-general] What is the current wiki-poliicy for re-writing contributions?
silverhammermba at gmail.com
Tue Mar 22 15:35:58 UTC 2016
> Under what criteria does this take place? It has gotten to the point
> where you
> just get tired of helping -- why bother?
The main criterion is this:
Specifically, "Before writing a specific procedure in an article or
describing something in particular, always check if there is already an
article that treats that part in detail: in that case, link that article
instead of duplicating its content."
This is not some conspiracy to "obfuscate information as much as possible",
it is a matter of practicality for maintaining the wiki. I see the
usefulness of all-in-one tutorials that users can simply read from start to
finish, but such tutorials come with their own problems:
- They often duplicate content from multiple articles. That means that
they can quickly become inaccurate as other articles are updated, making
wiki maintenance much harder.
- They have to balance between simple/general and complex/specific. A
general tutorial is most likely going to omit important information for
some users, leaving some users struggling with errors or missing
functionality. However a more specific tutorial becomes bloated as it tries
to address corner cases, making it harder to read, and even more
susceptible to the problem of article duplication.
- By providing a "one-stop shop" they discourage users from reading
important articles. The fact is that some aspects of Arch Linux are just
complicated: they might require reading multiple long, complicated wiki
articles in order to understand them. Every time you say "Just do X, Y, and
Z" without giving the full context of these actions, you are sacrificing
short-term readability for potentially more confused users in the long
term. See also
For example, take this discussion prompted by one of my big reverts of the
AUR article: https://wiki.archlinux.org/index.php/Talk:Arch_User_Repository#Uploading_AUR_Packages.2C_AUR
Someone wanted to make the AUR article easier to read for new maintainers
by adding a quick git intro for AUR4. Being an AUR maintainer means you
need some familiarity with git, so this quick intro objectively made the
article easier to read. So why did I revert it? Having worked with git
professionally for years and having taught git to many, many people I know
that it can be an extremely confusing tool even for people already familiar
with other version control tools. Looking at that intro, I could picture
the hoards of confused new AUR maintainers in the AUR subforum with
horribly mangled git repositories on their hands because their only
introduction to git was a tiny subsection of the AUR article. Being an AUR
maintainer means using git, and git is complicated, so you need to take
some time to learn it. Is that bad writing? Is that obfuscation? Is that
elitist? I think it's just the way things are.
All of that being said, I am not against including tutorial-like articles
on the wiki. As long as they are clearly marked and kept separate from the
main reference articles, I see no problem. I particularly like Kenneth's
idea of having a Tutorial sub-article e.g.
would be even better if we could add a Template:Tutorial to such articles
like "This tutorial may not cover every use-case. Consult the main article
for comprehensive information and troubleshooting."
More information about the arch-general