Difference between revisions of "Help talk:Style"

From ArchWiki
Jump to: navigation, search
(Style vs. Usability: my thoughts on the matter)
(Style vs. Usability)
Line 97: Line 97:
::::::** Install package: {{ic|pacman -S package}}
::::::** Install package: {{ic|pacman -S package}}
::::::-- [[User:Pointone|pointone]] 12:33, 15 January 2012 (EST)
::::::-- [[User:Pointone|pointone]] 12:33, 15 January 2012 (EST)
This debate ended up very lively with strong arguments from both sides, I'd like to present a new side to the same argument. I much enjoyed the fact that the "old" method of signifying an installation action provided a clear optical action point; compare if you will:
$ pacman -S package1 package2
NTPd can be [[pacman|installed]] with the package {{pkg|ntp}}, available in the [[Official Repositories]].
The "old" method clearly signifies action should be taken, the new method suggested in the style documentation is far easier to miss in a large document. Furthermore, this new method reads more as a tip or a notice than an action statement, is that desirable or recognizable? --[[User:Stefanwilkens|stefanwilkens]] 15:42, 17 January 2012 (EST)

Revision as of 20:42, 17 January 2012

Protection notice

This style guide is an official document of the ArchWiki, and is protected so that only users with administrator privileges can edit it. This is necessary to ensure sufficient stability over time, since frequent, undiscussed changes to its rules would defeat the purpose of the guide itself.
It is probably needless to say that the protection of the article makes this very talk page the most important and effective place for discussing every possible improvement to the guide, from the correction of small typos to major changes like the introduction of new rules. Every report or discussion is welcome and will be answered as soon as possible. However, if an existing style rule is under dispute, its current state remains enforced until it is changed, if that ever happens.
This guide was born after several months of discussions among the administrators and the most active contributors at the time, and it is a compromise among their ideas and those of who has been contributing until now. While new ideas and proposals that are coherent with the guide will probably be accepted and implemented, it is also likely that the requests that aim to radically change the way a particular style issue is already addressed will be discarded. We all must acknowledge the fact that it is reasonably unrealistic to think that all the ArchWiki users will ever completely agree over all the style rules, that is why it becomes necessary that final decisions be made by the administrators: we hope that this concept will be peacefully accepted by everybody, so that we can all collaborate in a more constructive way.
Thank you for reading this notice and for contributing to the ArchWiki! -- The ArchWiki Administrators 21:27, 14 January 2012 (EST)

Edit summary

See Help talk:Style/Edit summary.

Package installation

See Help talk:Style/Package installation.

Article summary templates

See Help talk:Style/Article summary templates.

Migration to new Code formatting templates

See Help talk:Style/Migration to new Code formatting templates.

Category pages - tree or otherwise?

The ArchWiki category tree was originally designed as just that: a tree. I disagree with the point: A category can be categorized under more than one category, provided one is not ancestor of the others. I believe that categories should themselves be categorized under only a single category. Non-overlapping categories should be devised in cases where one category could belong to many. Related categories can be listed on the category page itself. -- pointone 10:39, 23 September 2011 (EDT)

As noted at the top of Table of Contents, Category:Secure Shell (English) is a good example: if we can solve it we can really try to avoid categories with multiple parents in general, which is something that I don't like either. The problem is that Security could hardly be child of Networking, and vice versa, so either we put Secure Shell only under one of them, or for example we split Security in two categories, one under Networking, the other not, and put Secure Shell under Networking->Security. Of course we could also split Networking instead, but it would probably be less natural. -- Kynikos 11:43, 23 September 2011 (EDT)
Is there any decision on this? I would like to add Category:Package development (English) as a subcategory of Category:Package management (English). Currently it is only a subcategory of Category:Arch development (English). But there is no point in me doing that if it is just going to be undone. Otherwise I would add a manual link from Package management (which may have helped me find what I was originally looking for) and probably a reciprocal one back the other way. But I feel that is more work than necessary and when looking for information on the wiki I expect the categories to work this way instead.
 Why were the Arch wiki’s categories originally designed as a tree? Why do you prefer that categories only have a single parent category, especially when article pages do not have to? Vadmium 10:52, 26 October 2011 (EDT).
No decision yet, the current style rules allow multiple parents also for categories, so you can implement your idea, don't worry now whether it will be undone or not in the future. Just remember to update Table of Contents or Talk:Table of Contents (I don't remember which one is the most up-to-date) and to link to this discussion from the Edit Summary.
In general, a tree-like structure is the "ideal goal" because it looks simpler and tidier than having "converging branches", thus helping organizing the articles in a more natural way and also making maintenance easier. However it may be hard to put into practice indeed, so this discussion is probably going to last long...
-- Kynikos 12:59, 27 October 2011 (EDT)


This is a bit off-topic, so move this to its own section if appropriate, please.

Am I the only one that finds the i18n sections to almost be more trouble than they are worth? The vast majority of the i18n pages I have seen are either months out of date, are missing a lot of formatting (such as Filename, Codeline, etc.), have half of the page in English and the other half in the correct i18n language, and other such nonsense. Would it make more sense to get rid of the i18n sections entirely and to dedicate all of our effort on making sure that the articles we have in English are written in the most "translator friendly" manner possible (e.g. no contractions, no slang, etc.)? I am not familiar with how well free services like Google Translate work when going from English to [insert non-English language here], but it might be worth looking into. It would probably make sense to keep the official installation guides written directly in the non-English languages, but it is simply not feasible to properly maintain i18n pages for every page on the wiki. -- Jstjohn 01:56, 10 October 2011 (EDT)

Also, with the rise of Google Chrome which basically has Google Translate built into the browser, I would guess that doing this would not be as big of an inconvenience to our non-English users as it would have been a couple years ago. In fact, I would bet that using Google Translate via Chrome would be more convenient for our non-English users than having to deal with significantly outdated instructions (and the troubleshooting/damage control that will almost certainly occur from way-out-of-date guides). -- Jstjohn 02:09, 10 October 2011 (EDT)
The idea was that other languages move to their own wikis, like German, French and Polish did.
Another issue: there's currently no way to search within one language only, so you get 5 useful links in twenty. -- Karol 03:32, 10 October 2011 (EDT)
As Karol says, in theory each language should have its separate wiki. But in practice it's not how it works, and for sure we cannot just "get rid" of all the non-English articles, we'd throw away the efforts that many users have done over the years, trying to make the Arch documentation available also to those who can't read English.
Google Translate, although managing to achieve quite impressive results, cannot really handle intricate sentences, or slang, idioms, or technical terms, and anyway it needs correctly-formed English sentences to work well, which is not always the case.
About the search issue, the "language" information of an article is stored only in a standard substring of the title (the _(Language) suffix), AFAIK there's no "Language" field in the database, so there's probably no built-in function to filter a search by language. Asking Arch's web developers to implement one by themselves would rightly result in a "we don't want to maintain such a change, go ask upstream, closed" or something like that.
-- Kynikos 15:53, 10 October 2011 (EDT)
There have been a number of discussions about this over the years: 2006, 2007, 2009, and 2010. In short, there are a number of potential solutions; none are perfect. Currently, the interwiki implementation is considered "best" because it provides non-English users with a fully-localized experience and isolates each language. Other "good" solutions include the creation of language-specific namespaces or migration to a different wiki which provides "better" internationalization options -- but require more effort to implement. In brief: the i18n bar will eventually disappear. -- pointone 17:36, 10 October 2011 (EDT)
Uh right, I didn't think of the namespace solution, it may be the most practical to implement with a relatively little effort!
Another disadvantage of the i18n template is that statistics like Special:LonelyPages and Special:DeadendPages don't work anymore as expected.
-- Kynikos 17:50, 10 October 2011 (EDT)

Style vs. Usability

Commenting on: Help:Style#Daemon_operations and Help:Style#Official_packages

Deprecating installation instructions and the method of adding deamons to the DAEMON array is causing a higher than normal amount of questions on how to do this in the IRC channel. Perhaps this can be reconsidered, or at least be reconsidered for critical articles like the beginner's guide, the dbus article, the official installation guide, the various graphics driver pages (ATI /NVIDIA) etc etc. These are often browsed from CLI during installation and should thus be as complete as possible, having to follow links around and back from a CLI browser is no fun.

And in general: Having to look up the method of applying a change mid-article kills the flow of the article, users have to browse around to find a system-critical method on a different page.

This would be fine if the action involved wasn't so important, or if the linked information was either:

  • a small non-critical note
  • a large block of text requiring separate attention

but these actions are system critical. We don't want to create confusion in guide-nature articles. --stefanwilkens 18:18, 10 January 2012 (EST)

All newcomers should read Beginners'_Guide. Is there anything missing from that article or is anything not clear and easy to understand? It tells you how to add a daemon and install packages. -- Karol 18:19, 10 January 2012 (EST)
That page is in such a proper state because the policies in Help:Style#Daemon_operations and Help:Style#Official_packages haven't been applied there. The flow would be broken if they were. I'm trying to point out that applying these policies to all our articles would needlessly complicate things for the users reading these articles.
TLDR; an article telling you where to find how to do something rather than telling you how to do something within the article itself is incomplete, confusing and doesn't flow.--stefanwilkens 18:43, 10 January 2012 (EST)
I'm a fan of DRY so -1 for your suggested changes. People can't be bother to RTFM, nothing new.
Both Daemon and pacman articles should have the info you (the people you're trying to help) need. -- Karol 18:55, 10 January 2012 (EST)
This part of the wiki styleguide tells you explicitly 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. -- Karol 19:39, 10 January 2012 (EST)
DRY is a philosophy originally intended for software development to prevent code duplication. While it is applied to documentation, surely applying DRY over article clarity isn't a good thing.
I refer you to random articles on other distro wikis out there:
It is standard practice in distro documentation land to include installation instructions in every article, and for good reason. It works, it's obvious and it's clear to the reader without having to find more documentation to explain the documentation he's reading at the moment. Your argument that they should have read other documentation makes sense and is sound, but we shouldn't forget that these articles are written with the single purpose of clarification. Where does one draw the line between preventing rehashing of information and sacrificing article sanity?
I do agree that rehashing complete articles of information is pointless, a good example of referring to external information is the nvidia, ati and Desktop_Environment articles that had their content removed from the Beginner's_Guide and the xorg articles. This is useful because a user following links to those external articles will likely have to follow the extent of it, it flows well to do so. That and the silly amount of information that was essentially duplicated between the articles made for sound reasons to link rather than rehash.
Forcing people to look up one-line information in large external articles is just silly, especially if that information is core to the system. You're not reducing the article's complication, you're not reducing the article's size in a significant way and you're complicating the flow.
This is basic info and knowing how to install packages or add daemons is covered in the wiki in the places you'd expect: in the beginners' guide and in daemons and pacman article respectively. How can the lack of this info be a problem for any Arch user? -- Karol 06:38, 11 January 2012 (EST)
The current initscripts (2012.01.2-1) have manual page for rc.conf. It's the first incarnation so it may need some work e.g. in the daemons section. Users of course have pacman and pacman.conf manual pages at their disposal.
I understand that you're asking for just a one-line change here or there, but it's like having each pedal in a manual transmission car marked 'clutch', 'break' and 'acceleration' respectively. I see no reason users shouldn't be expected to know this stuff. -- Karol 07:07, 11 January 2012 (EST)
As for "look up one-line information in large external articles", it is not the goal of providing an external link. When a user want to use Arch and install software, he should/must read all pacman, learn all about it and remember most often used command "pacman -S ...". Then he will never need to follow these external link any more. And his mind will never be distract by a command which is right in the memory. Fengchao 20:49, 11 January 2012 (EST)
Yup, we should think about experienced users too - I don't think they want to read the same info over and over again :-) -- Karol 22:08, 11 January 2012 (EST)
"Deprecating installation instructions and the method of adding deamons to the DAEMON array is causing a higher than normal amount of questions on how to do this in the IRC channel." I believe that if an Arch user cannot remember how to install a package (pacman -S package) or to edit a text file (rc.conf) then it's even more important that he takes the time to read pacman, rc.conf and Daemon, because those articles are among the foundations of an Arch Linux system, and there's no way their content can be ignored. Arch users can't be made to think that an Arch system can be administered like more user-friendly distros such as Ubuntu, openSUSE and similar, the average Archer is required to be more aware of how his system works than the average Ubuntu user, that's by Arch's design in the first place.
That said, the Beginners' Guide is the only article that is exempt from the rules about installation and daemons. I'm taking note that this exemption is not explicitly stated and I'll fix that asap!
The current style guide was discussed for several months (see the history of its talk pages) among the administrators and the main contributors at that time, and it's a compromise among all the different ideas and opinions we expressed during its development. We agreed that a style guide enforced by the admins is necessary since there's no way that all users will ever find a common point of agreement over all the style rules, and this very discussion, (although very welcome, like every discussion ^^ ) is just an example of that consideration.
I'm sorry but I have to reject your proposal, since it wouldn't be an improvement of the style guide, but a change in its direction, and that would require a much larger discussion, considering that all the current active administrators support it the way it is now :)
-- Kynikos 09:35, 11 January 2012 (EST)
Maybe one thing that could be evaluated, if some users are really ignoring links to those articles, is using more explicit links like "Installhow? the xyz package, available in the Official Repositories" as was proposed by James Eder on 3 June 2011 (see history). The <sup>[[pacman#Installing_packages|how?]]</sup> part could be included with a specific template (we couldn't include also the rest of the sentence because it must be adaptable to package lists, groups and more possible particular situations). Something similar could be done for daemons and kernel modules. However this would be a compromise, I still prefer the implicit link in the word "install". -- Kynikos 12:30, 11 January 2012 (EST)
The style suggested by the guide for installation of packages is unnecessarily verbose. The ArchWiki must be as concise and as usable as possible. If users want more in-depth documentation, they can consult a manpage or the project's official documentation. The instructions Template:Box are far clearer and more effective than Template:Box KerrickStaley 11:26, 12 January 2012 (EST)
I have only read the last two responses to this section, but I wanted to make a more general point. Far too much online documentation is dumb, meaning it tells the reader what to do, without explaining the underlying concepts. I believe the use of a sentence instead of a command helps the reader understand package installation more broadly. Many users are too quick to add commands and scripts to the Wiki without explanation. The switch from the pacman -S <package> to the aforementioned sentence will hopefully be the first step in encouraging more thorough explanation. Commands should be used sparingly. ~ Filam 17:45, 12 January 2012 (EST)
We can get the best-of-both worlds if we first give instructions on exactly what to do, and follow those instructions with explanation. That's what I always strive to do when writing articles, but when installing packages, there's really no explanation necessary; it's a task the user must have done several times before they can even be browsing the ArchWiki.

More generally, documentation that gets to the point instead of beating around the bush is better. Lay out the main points first, and then mention the fine details, exceptions, etc.

Also, if we're going to use a sentence rather than a command line to explain which packages need to be installed, then a fixed sentence with minimal verbiage is better: "Install <package(s)>, available in the Official Repositories". It's easy to tell at-a-glance which packages are needed.

KerrickStaley 22:22, 13 January 2012 (EST)
"...it's a task the user must have done several times before they can even be browsing the ArchWiki." Well, that problem can't be solved in the ArchWiki then. By the way the Beginners' Guide is exempted from the disputed rules, and now I've also stated that explicitly in the guide.
The minimal verbiage is recommended, in fact it's the one used in the main examples in the guide, but installation requests do not always come at the beginning of articles in installation sections: sometimes they are in tips and tricks sections, or troubleshooting, or in general are part of a longer sentence and require a specifically adapted wording that we can't predict with a style rule.
-- Kynikos 10:33, 14 January 2012 (EST)
A couple points from my perspective:
  • The current style rule is more generic; for the same reasons why yaourt -S package is discouraged, pacman -S package should be too. Pacman may be the default package manager but not everyone needs to use it -- many AUR helpers also work with the official packages and other pacman wrappers exist (e.g. pacman-color). Further, some people may wish to compile their own packages with ABS before installing, etc.
  • Even if pacman -S package is preferred, this doesn't really tell the whole story. Proper (complete) installation instructions should read:
    • Ensure the correct repositories are enabled: nano /etc/pacman.conf
    • Ensure that a server (or two) is uncommented in the mirrorlist: nano /etc/pacman.d/mirrorlist (check online for up-to-date mirrors)
    • Update your system and refresh your package lists if you have not yet done so today: pacman -Syu
    • Install package: pacman -S package
-- pointone 12:33, 15 January 2012 (EST)

This debate ended up very lively with strong arguments from both sides, I'd like to present a new side to the same argument. I much enjoyed the fact that the "old" method of signifying an installation action provided a clear optical action point; compare if you will:

$ pacman -S package1 package2

NTPd can be installed with the package ntp, available in the Official Repositories.

The "old" method clearly signifies action should be taken, the new method suggested in the style documentation is far easier to miss in a large document. Furthermore, this new method reads more as a tip or a notice than an action statement, is that desirable or recognizable? --stefanwilkens 15:42, 17 January 2012 (EST)