Difference between revisions of "Help talk:Style"

From ArchWiki
Jump to navigation Jump to search
(Daemon operations)
m (Make discussion pages part more visible: Sign my edit...)
Line 457: Line 457:
* Add a link to this page on all Talk pages. Do not know whether it is easy to do directly from the MediaWiki. Even if it is hard to do automatically, we can add something such as:
* Add a link to this page on all Talk pages. Do not know whether it is easy to do directly from the MediaWiki. Even if it is hard to do automatically, we can add something such as:
{{Note|This is discussing page, please read [[Help:Talk]] for a guidline. Use {{ic|<nowiki>-- ~~~~</nowiki>}} to sign your edits.}}
{{Note|This is discussing page, please read [[Help:Talk]] for a guidline. Use {{ic|<nowiki>-- ~~~~</nowiki>}} to sign your edits.}}
-- [[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 09:27, 17 October 2012 (UTC)

Revision as of 09:27, 17 October 2012

Read this first

Help:Style 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 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 as a subcategory of Category:Package management. Currently it is only a subcategory of Category:Arch development. 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)

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)
But who is the target audience of this documentation? Surely it's easier for an advanced user to skip information he / she does not require than for a less advanced user to have to refer to other articles. The likes or dislikes of users shouldn't affect the documentation and it most definitely should not be a argument to make the documentation less accessible, which is pretty much what this comes down to.
Unless the hand-holding and increased accessibillity of our documentation to less-experienced users is a goal here. I know we don't strive to support the mentally challenged here, but we should prevent this from influencing the documentation? Two-sided coin I suppose. --stefanwilkens 15:51, 17 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?

I believe this is similar to what Kynikos suggested a few blocks up, on 12:30, 11 January 2012 (EST)--stefanwilkens 15:42, 17 January 2012 (EST)

Yeah I suggested that only as a possible compromise, although I still prefer the current phrasing. You're perfectly right, those who are used to reading only the blue parts in the articles will miss the installation parts with these style rules. But do we really want to accomodate to their needs? Words, even if on a white background and in variable-width fonts, have a definite, most often useful meaning, they have not been put there for aesthetic matters or by mistake. I don't think your argument is convincing, but let's see if somebody else has something to add. -- Kynikos 16:39, 17 January 2012 (EST)
Accommodation to the needs of experienced users (dislike reading hand-holding articles) is brought up as an argument a few blocks up from here. Why accommodate one group over the other? This is likely a question of who the target audience is. Is there a guideline on this at all? Is our documentation intended to let the novice users successively install / operate Arch Linux and anything we may describe in our WiKi or do we set the guideline that we expect more?
I think I may have answered my own question as I wrote this, but for the sake of consistency. What is the target audience?
As for the style, I would be inclined to add indentation or something else to attract attention to these to-be-installed lines. Visited links on our style turn grey, the line really does blend in with the article if all links in it are visited previously. Would additional attention be acceptable?--stefanwilkens 18:14, 18 January 2012 (EST)
The information is still available on the wiki and linked to when relevant. In my opinion, duplicating instructions everywhere doesn't help new users. Instead, it provides them with many sources of incomplete and often out-of-date/inaccurate information rather than directing them to an high-quality article.
I understand that there's a steep learning curve, but hand-holding instead of teaching just prolongs it. Arch was my first experience with Linux and I had zero command-line knowledge. I ended up doings lots of reading (mostly the wiki at first, eventually other documentation) and worked through the issues I encountered. At that point the Beginners' Guide was a huge mess because it had many step-by-step branches (instructions for installing a dozen DEs/WMs and mouse cursors/themes!).
If we just provide copy-and-paste commands everywhere we don't provide much opportunity to learn, and just teach users to turn to the forums or #archlinux at the first sign of trouble (instead of relying on the community as a fallback when they've already done research and tried to figure it out for themselves). Relevant: http://slash7.com/2006/12/22/vampires/.
Linking to well-written and maintained articles makes it much easier for someone to go from being a new user to an experienced one; you only have to learn how to install/remove/downgrade a package once (likely just when you need to do it) and then you're set forever. It will make it harder for people who don't want to read or learn and just enter commands copied from the wiki, but I don't think we should encourage that.
Give a man a fish and you feed him for a day. Teach a man to fish and you feed him for a lifetime.
- thestinger 21:21, 18 January 2012 (EST)
This comments on the content and overall tone of the article. Both "old" and "new" suggested methods of displaying the information contain equal content, I don't think we're loosing content or significantly avoiding hand-holding behavior at all with this new style. I accept that my initial argument on the removal of terminal style installation instructions has passed, but that's not what I'm trying to talk about in this section.
My debate here is that of readability, how to best present this information to a reader. Regardless of article tone, what optical structure is best used to signify key action points in the article. See the example 4 blocks up and take note of the significantly reduced visibility of these actionable points (something your link talks about). If we are to write actionable documentation, should we then not make sure that the directly actionable sections of the documentation are prominent?
Open up any textbook, examples are always provided in colored blocks, other fonts, indented notation or preceded by colored or otherwise optically attracting constructs. The suggested style blends in with an article, especially when the links in it are marked "visited" (grey) --stefanwilkens 07:19, 19 January 2012 (EST)
Changing the color of visited links has been in my todo list for some time, maybe it's time to submit a bug for that: I'd like to see a purplish color, I tried something like #606, #70b, #74b. More ideas? Objections?
-- Kynikos 08:33, 19 January 2012 (EST)
Note that interwiki links already become purple (albeit still too greyish?) when visited: wikipedia:Main Page wikipedia:Main Page. -- Kynikos 15:25, 24 January 2012 (EST)
I'd also like to request that links remain bold even when they are in indented paragraphs (#bodyContent dd > a {font-weight:bold;} ?) -- Kynikos 11:46, 29 January 2012 (EST)
Completely agree. Also, I think, color should be different from one of interwiki links. --AlexanderR 23:54, 29 January 2012 (EST)
Do you mean of a completely different color? Can you be more specific or give an example? In any case if there should be a difference in color among links, it should distinguish internal from external links (including interwiki).
However I think that black for normal text, blue for links (internal or external), purple for visited links and black on cyan for code may be already enough.
-- Kynikos 07:11, 31 January 2012 (EST)
>> Do you mean of a completely different color?
No, a bit darker shade than #606 (or, maybe even a bit more rich) would be perfect. --AlexanderR 00:29, 4 February 2012 (EST)
More about visibility: we could evaluate (which means I'm not supporting yet this idea, i.e. I'm brainstorming) the possibility of adding a little inline package icon at the end of Template:Pkg and Template:AUR in a similar fashion to what happens with regular external links, that get a little arrow. Thoughts?
I'm strongly against indentation as it won't work with installation requests that are included in longer sentences.
-- Kynikos 08:33, 19 January 2012 (EST)
If the icon for official packages is different from the one for aur packages, this may also let us avoid always adding "available in the official repositories" and "available in the AUR". -- Kynikos 11:46, 29 January 2012 (EST)
Well, if you find suitable icons. --AlexanderR 23:54, 29 January 2012 (EST)
Edit: and develop alternative presentation for text browsers --AlexanderR 23:54, 29 January 2012 (EST)

Title case

As discovered in Talk:Common Applications#Improving the title, the rule regarding title case is currently unclear (and absent from this style guide). Help:Editing#Creating pages states Titles should be capitalized appropriately: Title for New Page; not Title for new page.

I propose the following style rule to be added under Help:Style#Title (as the first point):

  • Titles should be capitalized using title case, as in "How to Install Arch Linux on a Toaster."

Any objections or suggestions before I add this? Do you think it is necessary to contrast with the rule for headings (which should use sentence case)?

-- pointone 16:37, 19 January 2012 (EST)

Of course we need a rule for title case. Referring to "Title Case" should work in the majority of cases, however I'd use "How to Easily Install Arch Linux on a Blue Toaster" or something like that as an example, just to include an adverb and an adjective (assuming I've capitalized them correctly).
Then we should probably also mention the correct way to capitalize the application names that are officially written in lower case, and this would probably need a reference to Template:Lowercase title, which by the way I wanted to mention at the first position in Help:Style#Layout, together with some behavior switches.
I don't think it's necessary to explicitly contrast this rule with that for section headings.
-- Kynikos 07:16, 20 January 2012 (EST)
This topic has been touched on also in Talk:Article Naming Guidelines#Article title capitalization, mentioning Wikipedia's policy which seems to conflict with the "title case" idea. -- Kynikos (talk) 11:49, 5 July 2012 (UTC)

Reducing formatting bloat

I noticed that some articles tend to become almost unreadable after long editing – mostly due to extensive usage of bold/blue text and code formatting templates. Does anybody feel the same? To start with – here is my proposal: prohibit usage of Template:Ic inside Template:Note, Template:Tip and other similar templates. Such templates already attract a lot of reader's attention, there is no need to bother one even more (and IMHO combination looks ugly). --AlexanderR 03:39, 25 January 2012 (EST)

Honestly I like how code formatting templates make code recognizable even at a glance in a block of text, even inside Notes, Warnings and Tips. Forbidding the use of Ic inside those templates would generate:
Tip: You can run rm -rf / as root to free some space on your hdd.
Instead of:
Tip: You can run rm -rf / as root to free some space on your hdd.
I find the second template much more readable and clear than the first one.
That said, it's worthy of mention the solution used in Python's official documentation (code inside Notes and Warnings gets a darker background than the surrounding background color), but we can't implement that here because we'd have to play with css classes.
-- Kynikos 16:12, 25 January 2012 (EST)
Nice tips. Nearly gave me a hear attack ;P -- Karol 16:50, 25 January 2012 (EST)
AlexanderR, can you give some examples, which articles look bad to you? -- Karol 16:50, 25 January 2012 (EST)
This is not whole article but IMHO still counts: MySQL. There are several instructions like this:
edit /etc/rc.conf and add mysqld to the DAEMONS array.
Link to rc.conf is almost invisible and actually is not helpful for ones who do not remember what daemon is. For me this looks a bit better:
add mysqld to the list of daemons in /etc/rc.conf
--AlexanderR 00:12, 29 January 2012 (EST)
Link to rc.conf is perfectly visible for me - it's blue and underlined.
As for people "who forgot what XYZ is", they can always check it in the wiki, e.g. by searching for 'XYZ', but adding link to the daemons article seems reasonable. -- Karol 06:13, 29 January 2012 (EST)
In any case it's true that we're missing an official phrasing like those for installation requests. I like:
Add example to the DAEMONS array in /etc/rc.conf.
[[Daemon#Starting on Boot|Add]] {{ic|example}} to the {{ic|[[DAEMONS]]}} array in {{ic|/etc/[[rc.conf]]}}.
We should probably start a poll after we have collected some ideas here. The same should be done for immediate starting/stopping/restarting of daemons, for adding kernel modules to the MODULES array and for immediate adding/removing of kernel modules.
@karol: internal links become gray with the default theme when visited, and I agree they lose a lot of visibility (unless you move the mouse over them) see one of my proposals at the bottom of #Style vs. Usability.
-- Kynikos 11:32, 29 January 2012 (EST)
>>Add example to the DAEMONS array in /etc/rc.conf.
Does not look good for me. Three links in the single sentence? Two of them to the same article? How is rc.conf related to the entire concept of daemons? E.g. what is the purpose of linking to rc.conf in such phrase? Also mentioning DAEMONS array, /etc/rc.conf and other details would only become a disservice if implementation changes in future. Anyway, managing daemons autostart is more complicated process than just adding/removing entries within some array. Users should also be able to understand which daemons specific one depends on, how to perform lazy (parallel) loading etc. In other words, average Arch user should know contents of Daemons just like Pacman quite well and highlighting /etc/rc.conf together with single link to Daemon should be enough to trigger all required associations.
About formatting: highlighting file names and random code lines by means of pale bluish background is already common in Wiki and looks really cool. But, IMHO, it would be nice to use bold text more intensively: for names of kernel modules, daemons, random executables. Note, that unlike Template:Ic bold formattiong works also in console browsers (at least Links and Lynx can render it noticeably).
--AlexanderR 23:44, 29 January 2012 (EST)
Another example from PulseAudio:
make sure the module snd_pcm_oss is not in the MODULES array in /etc/rc.conf
(is link to rc.conf visible for you?)
--AlexanderR 20:00, 30 January 2012 (EST)
AlexanderR, I fixed the link in the PulseAudio#ALSA example you gave. However, I understand what you mean. I often find that most authors prefer to just write commands without enough explanation. I have certainly done it myself. That can make the formatting stand out. I find the PulseAudio example far more reasonable than the MySQL example you gave earlier because there is more context around the formatting. ~ Filam 22:44, 30 January 2012 (EST)
In the My SQL example, that “Add” link is like Wikipedia’s easter egg links, which I find annoying. Linking to Daemon and introducing the mysqld script should probably be done even earlier in the article; this snippet should just be explaining how to run that script at boot time.
In the OSS example, from a technical point of view, the link is hidden because its formatting is overridden by the inner {{ic}} template. If you add text around it (the /etc/rc.conf file) it might be clearer why. It works if you put the link inside the code ( /etc/rc.conf) or if you use plain <code> tags (/etc/rc.conf). Personally I’d just go for a plain link (/etc/rc.conf) because the formatting of the link is enough emphasis for me, but I understand many people wouldn’t agree. Vadmium 23:14, 30 January 2012 (EST).
Ok guys you surely have some points about this, I'd like to concentrate especially on two things that AlexanderR has rightly pointed out (I'm rewording them, please correct me if I got them wrong), so I'm splitting the discussion here:
  1. #Daemons and modules wording
  2. #Bold and italic
I am personally against any formatting at all, at least where it can be avoided. IMHO, if we want formatting in articles to be meaningful and helpful for readers, it is necessary to completely deprecate it's usage except limited list of well-defined cases. Such lists would obviously tend to change, but at least this would help to prevent counterintuitiveness and inconsistency. --AlexanderR 20:45, 3 February 2012 (EST)

Bold and italic

Currently the style guide completely ignores bold formatting, which instead could probably be used in some cases in place of Template:ic. Let's include also italic in the discussion. Is there the possibility to have well-defined rules (applicable in real articles) about when to use Template:ic, when to use bold and when to use italics?

-- Kynikos 16:17, 31 January 2012 (EST)


With respect to this Wiki specificity (and taking into account various precedents) I propose to limit usage of bold text to: --AlexanderR 19:44, 31 January 2012 (EST)
  • Highly questionable: single file names
search for loop.ko in /lib/modules/kernel_release
--AlexanderR 19:44, 31 January 2012 (EST)
  • executables names (as executables in file system, not in command line):
javaws, which is in icedtea-web-java7
Template:Box YELLOW
--AlexanderR 19:44, 31 January 2012 (EST)
  • kernel module names
ensure that radeonfb is blacklisted
--AlexanderR 19:44, 31 January 2012 (EST)
  • important part of file/command line contents:
root=/dev/sda6 ro 5 radeon.modeset=1 vga=current logo.nologo quiet splash
--AlexanderR 19:44, 31 January 2012 (EST)
This one can be acceptable. -- Kynikos 17:58, 3 February 2012 (EST)
  • name of application in the beginning of application-related article
Foo is the most popular Linux alternative to Wikipedia:Bar.
--AlexanderR 19:44, 31 January 2012 (EST)
I don't know, usually the name of the application is also the title of the article, so this rule could just add bloat for nothing. I'd recommend to use the first encounter of the app name as an anchor for a link to the official website instead. If there's nothing to link, leave it in normal weight. -- Kynikos 17:58, 3 February 2012 (EST)
>> so this rule could just add bloat for nothing
Maybe, but for some reason cited HTML5 developers, authors of many articles in this Wiki and even http://www.archlinux.org/ webmaster believe this to be "conventional typographic presentation". This, however, does not oblige us to support such case of usage here.
>> I'd recommend to use the first encounter of the app name as an anchor for a link to the official website instead.
This is neither consistent (there is often nothing to link) nor intuitive – user can not see link destination without hovering cursor over it. As I said in discussion on "See also visibility", links to Wikipedia article(s), application home page(s), application project(s) on code hostings etc. together with reliable summary are the only reasonable content for article summary template and should probably be placed in that single predefined place. --AlexanderR 20:45, 3 February 2012 (EST)
  • I don't know if we should use bold or what else when using pseudo-variables like:
# modprobe module_name
# modprobe module_name
# modprobe <module_name>
# modprobe [MODULE_NAME]
(from Kernel Modules). -- Kynikos 17:58, 3 February 2012 (EST)
This conflicts with "important part of file/command line contents" part. As I said below, italic seems to be more appropriate.
Probably worse idea than just italic: Another proposal –
# modprobe <module_name>
This way pseudo-variables become highlighted and offset from surrounding text at the same time but in different way than "important part". --AlexanderR 20:45, 3 February 2012 (EST)


I already noticed two kinds of italic usage in this Wiki, conventional enough to be proposed for this role (I am so lazy.. please add examples yourself if you want): --AlexanderR 19:44, 31 January 2012 (EST)
  • Cites from external sources:
All your data belongs to us – Google
--AlexanderR 19:44, 31 January 2012 (EST)
...or "All your data belongs to us" (w/ quotes)? (see e.g. Beginners'_Guide#The_Arch_Way) -- Kynikos 17:58, 3 February 2012 (EST)
This is matter of punctuation, not formatting. --AlexanderR 20:45, 3 February 2012 (EST)
  • Inline templates (IMHO, those with italic formatting look much better than ones with bold formatting):
--AlexanderR 19:44, 31 January 2012 (EST)
I don't understand, you'd use always italic inside Template:ic regardless of the content? In that case I don't even like it aesthetically :) -- Kynikos 17:58, 3 February 2012 (EST)
This is exactly what you name "pseudo-variables" (your wording was better than mine, lets use it). Using bold in this case conflicts with "important part of file/command line contents" part; italic would also be more intuitive: we want to offset text from its surrounding content rather than attract additional users attention. --AlexanderR 20:45, 3 February 2012 (EST)

Quoting and underlining

Also note that, although with less frequency, even underlining, 'quoting' and "double quoting" are used more or less commonly.

Let's go through this discussion treating one specific problem at a time, without rushing it, since this can be an enormous topic and with our current shortage of manpower there's not much we could do to correct the articles even if we managed to find a decent set of rules.

-- Kynikos 17:58, 3 February 2012 (EST)

Quoting and double quoting

Quoting belongs to punctuation rather than formatting, so there is nothing to discuss. --AlexanderR 20:45, 3 February 2012 (EST)


As far as I know underlining is used relatively rarely in this Wiki. The only use case I can imagine is using in place of bold (e.g. for highlighting single words and sentences without pulling them out of context). If we decide to deprecate direct usage of bold text in order to fully utilize it for technical purposes, such replacement would be suitable. --AlexanderR 20:45, 3 February 2012 (EST)

Daemons and modules wording

We need a more generic standard phrasing when requesting to "add daemons to the DAEMONS array..." (even avoid making reference to rc.conf, since Daemons links there already?) in the vein of what's been done with installation instructions, and point more clearly to Daemons. Similar problem with kernel modules and the MODULES array. Also the instructions for starting/stopping daemons and for adding/removing modules could be merged in the sentence.

I'd like to start a brainstorming session here to find the right wording example(s) to put in the guide. Of course objections to the whole idea are still taken into consideration.

We probably need a standard phrasing for immediate starting/stopping/loading/removing only, another standard for adding to DAEMONS/MODULES only and a third one for the cases where both immediate and automated action are recommended. I'll start with (I repeat, this is a brainstorming session):

  • "Start the foobar daemon."
  • "Load the foobar module."
  • "Add the foobar daemon to the DAEMONS array."
  • "Add the foobar module to the MODULES array."
  • "Start the foobar daemon and add it to the DAEMONS array."
  • "Load the foobar module and add it to the MODULES array."

Note that if we solve the problem of links color and font-weight as explained at the bottom of #Style vs. Usability, the links will always be blue/purple and bold, even in indented paragraphs. For now you can fake this effect by enclosing links in '''.

-- Kynikos 16:17, 31 January 2012 (EST)

  • I moved this part to the separate section as this discussion is not directly related to "formatting bloat" but rather to unification of phrasing.
  • Exact formatting depends on results of #Bold and italic discussion, so I propose to finish it before continuing this one.
>> objections to the whole idea are still taken into consideration
Well, I have already understood reasons for deprecating installation instructions and modules loading at startup/daemons autostart. All this is performed only once and there are a lot of troubles with giving command line snippets for this. But what's wrong with starting/stopping daemons? I'd better suggest to allow usage of snippets for this purpose but only for other reasons than creation of whole "Starting xxx manually" section, containing only that single line of code. IMHO, it is usually enough to mention existence and purpose of daemon in given package and providing link to Daemon. All daemons behave similarly, interaction with them in Arch is really simple; there is simply no need for adding same sections with same contents for every article. If writing snippet is really required to maintain workflow of step-by-step guide, then there is probably no need for restricting it (the same for loading/unloading) modules.
--AlexanderR 19:44, 31 January 2012 (EST)
Eheh with "whole idea" I meant the idea expressed in the first paragraph, since I was asking for possible methods of applying it without apparently leaving room for objections. I admit it wasn't clear at all :) So, just to give you an answer, it would look a bit inconsistent to me to allow daemon starting/stopping instructions and not installation instructions, also because we should resort to using snippets like:
You must now start the whatever daemon:
# rc.d start whatever
Which looks redundant to me, unless you wanted to suggest something like:
Now run:
# rc.d start whatever
Which I like even less because it's not teaching anything, it just leads the inexperienced user to copy-paste the command, without thinking of what he's doing.
If you had something different in mind, just give an example. -- Kynikos 18:20, 3 February 2012 (EST)
Again from PulseAudio:
Lets break workflow:
What looks better? --AlexanderR 00:37, 4 February 2012 (EST)
This argument seems rather circular. I fully support the last comment by Kynikos. And personally, I would combine the first two sentences in AlexanderR's second example to something like:
Since PulseAudio depends on the dbus daemon, start dbus and then start PulseAudio:
~ Filam 22:43, 4 February 2012 (EST)
Like this?
Looks nice, except usage of verb in link to daemon article: I agree with User:Vadmium about the fact that usage of such easter_egg links can a bit annoying and sometimes even misleading.
PS I am not going to challenge already reached agreement on deprecation of daemon instructions, so please consider adding something useful to #Quoting and underlining and #Bold and italic discussions, so that we can continue this one. --AlexanderR 00:40, 5 February 2012 (EST)

CSS updates

The style of <tt>, <code> and <pre> has recently been adjusted in the CSS to match that of code formatting templates.

I was wondering if now we should suggest using <pre> and space-initial lines instead of Template:bc in order to avoid having to add numbered parameters or <nowiki> tags when necessary. On the other hand, this may be seen as an incosistency since those hacks are still needed for its "sibling" templates ic, hc and keypress.

-- Kynikos (talk) 16:30, 4 May 2012 (UTC)

"Space-initial lines" are fine, but suggesting <pre> usage after so much effort put into getting rid of it does not look logical. --AlexanderR (talk)

Better structuring

IMHO, many parts of article can be safely moved to descriptions of corresponding templates. For example, information about Template:Keypress actually belongs to template itself rather than this style guidelines. I believe, most people look at template page before using it. What do you think? --AlexanderR (talk)

Actually this idea would overlap with a larger project I've had in mind for some time now: merging editing and style guidelines consistently everywhere, and split them in several articles based on the various topics being dealt with. However I'd like to plan this carefully in advance, as it involves several pages, otherwise we risk increasing the mess instead of reducing it. -- Kynikos (talk) 10:04, 14 May 2012 (UTC)
> ..merging editing and style guidelines consistently everywhere, and split them in several articles based on the various topics being dealt with.
Sounds good. Note, that moving part of current content to templates can reduce overall size of all involved articles and possibly simplify further work. --AlexanderR (talk)

Is it suggested to use Template:AUR for links?

During checking this edit I have suddenly realized that I do not know whether usage of direct links to AUR is right or not. If yes, than why, if no – where is the official rule regarding this? --AlexanderR (talk)

Actually this is the only rule proposed in Help talk:Style/Package installation that hasn't been enforced yet since we're still waiting for the resolution of FS#28839 which should hopefully be solved in the next AUR release.
The particular case you've mentioned, though, is an implicit installation request, and should be subject to Help:Style#AUR packages, with particular reference to the paragraph "You are granted the flexibility to adapt the wording to your specific article...".
-- Kynikos (talk) 10:52, 16 May 2012 (UTC)

Lists of related links

Inspired by [1], I was wondering if related links in "See also" sections or article summaries should be avoided if already present in the body of the article. I'd prefer having complete lists of related articles even if that implies duplicating some of them. -- Kynikos (talk) 11:09, 16 May 2012 (UTC)

> I'd prefer having complete lists of related articles even if that implies duplicating some of them
I'd prefer this way as well. Sadly listing all related articles may occupy most of vertical space, so there should be clear guidelines regarding choise of related links. And editors often don't have time to read even Help:Style... On the other hand, defining simple rule like "only links not present in text" can eliminate the very requirement for any additional rules. --AlexanderR (talk)
"only links not present in text" is too strict I think. Related links make some page more "visible" to readers. For example, I often click on them to learn more info about the same topic. But to be honest, I rarely click on the "in page links" even the links shown clearly in "See Also". They are much harder to be found and clicked. -- Fengchao (talk) 04:50, 19 May 2012 (UTC)

Definition of related link

Inspired by [2], I was wondering if we needed a definition of what are the conditions under which an article can be considered related to another one. Honestly I can't think of something suitable at the moment, if somebody has good ideas, they're welcome here. -- Kynikos (talk) 11:09, 16 May 2012 (UTC)

Few ideas:
  • Alternatives to software, described in article
  • Methods and techniques alternative to ones described in article
  • Software <-> it's use case
  • software/technique <-> it's developer
--AlexanderR (talk)

Request to change recommended package installation style

I find the existing recommended package installation instructions to be unsightly because of excessive blue links (see Help:Style#Package_management_instructions), and I feel that my proposed examples significantly boost readability of articles. I propose changing the official recommendation to the following:

Install package from the official repositories.

or my lesser preferred:

Install package, available in the official repositories.

The three primary changes are:

  1. removing the link to pacman
  2. removing the link to Official Repositories
  3. changing "Official Repositories" to lowercase

I see no reason why a link to pacman and Official Repositories is necessary on every article. If an administrator of an Arch box does not know how to install packages or know what the official repos are, then god help them and any other users on that box because they are in for a poor experience. The Beginners' Guide makes it very clear how to install packages and that the user must be familiar with pacman and how pacman operates.

For the [multilib] example on Help:Style, I think it is important to continue mentioning that a package is in [multilib], and I still support linking to [multilib]. I propose the following for a [multilib] package:

Install package from the official [multilib] repository.

-- Jstjohn (talk) 20:02, 15 June 2012 (UTC)

As for the wording itself, "Install package from the official repositories" sounds indeed slightly better than the current one, so I think we can replace it. The same goes for the multilib example.
About the capitalization of "[Oo]fficial [Rr]epositories" I'm completely neutral, so unless somebody has opposing arguments I'm updating it, although using one or the other form is still equally acceptable.
The links are clearly the main topic of this discussion: actually none of them is explicitly mandatory yet, so, just as a start, I'd like to state that at least the link to the package is needed.
About the links to pacman and the official repositories, we could make them optional, but recommend to use them in pages that may be targeted to less experienced users (e.g. articles directly linked from the Beginners' Guide like Xorg and so on).
As always, it would be helpful to read somebody else's opinion ^^
-- Kynikos (talk) 10:04, 16 June 2012 (UTC)
I'd be fine with recommending that the links be used on pages linked from the Beginners' Guide, etc. I just find it bothersome seeing links to pacman on every wiki article. :)
And I fully support making Template:Pkg mandatory.
-- Jstjohn (talk) 02:02, 17 June 2012 (UTC)
We are indeed familiar with pacman so to most people who know how to use talk page, the pacman link is not needed. But we should remember lots of people can not remember all pacman installation instruction after reading Beginners' Guide. When Arch wiki change from pacman -S <package name> to current style, many users did get lost and asking what to do even when the link is provided. Remove installation link will make Arch learning curve steeper.
-- Fengchao (talk) 11:03, 18 June 2012 (UTC)
I understand your concern, but I honestly don't know how Arch users cannot remember such a simple and often used procedure. Users should know to reference the Beginners' Guide or the pacman wiki articles if they forget basic pacman operations. To mitigate this unfortunate situation, I'm strongly leaning towards making some redirects to the pacman article. Notably install and install package, which I expect would be the most frequently used search terms if someone doesn't know how to install a package.
If we can create some good redirects for common searches like that, would your concerns be addressed (or at least partly)?
-- Jstjohn (talk) 23:03, 18 June 2012 (UTC)
Adding redirects is a good idea. Add all Arch users indeed remember it because who can not remember them before finishing reading Beginners' Guide will turn to other distro. :) I am not objecting here. However I did remember when change away from # pacman -S command line, many people object and complain. Had you read #Style vs. Usability above yet? We had a hard time to find a balance between different concerns for this style. Change it will stir things up again.
-- Fengchao (talk) 09:30, 19 June 2012 (UTC)
Ok, I've reworded the section, but I've decided we can't really get rid of links to pacman: installation instructions have been a very controversial style topic, and the current solution is some kind of a compromise to which I think we should adapt for the sake of consistency.
About those redirects, creating them can be helpful, even though there's a little (I guess negligible) chance that somebody following them is instead looking for an article on how to install Arch and not a single package.
-- Kynikos (talk) 10:48, 21 June 2012 (UTC)
Do we have the ability to make disambiguation pages, similar to Wikipedia, that we can use for the install redirect?
I'm going to create a redirect for install package and install packages now.
-- Jstjohn (talk) 13:58, 21 June 2012 (UTC)
Another complaint I have regarding the current package installation instructions is how much typing must be done simply to state "Install blah from the blah". It would be much easier/better, for several reasons, to create a package installation template which does this for us. I imagine it would function quite similarly to Template:Pkg except that it would put all of the verbiage around the package link. So, for example, using {{PkgInst|xmonad}} would produce the following auto-magically:
Install the package xmonad from the official repositories.
I don't have much preference for this proposed template's name. I initially kept the name short (e.g. {{Pi|xmonad}}), but I didn't want people to confuse that with pi. I went with {{PkgInst}} in my example because it is clearly different from Template:Pkg, but the similarity to/inspiration from Template:Pkg is hopefully obvious.
Because this only deals with official packages, it should be appropriate to create one for AUR packages as well. I propose that {{AURInst|opennebula}} would produce the following:
Install the package opennebulaAUR from the AUR.
-- Jstjohn (talk) 14:52, 21 June 2012 (UTC)
Let's leave Install uncreated for the moment: somebody may use it in installation instructions (Install package ...) and it would be confusing if it pointed to a disambiguation page.
About the installation template, it has been proposed already in the past, and just like other similar ideas (adding daemons to DAEMONS etc.) it has been discarded because it could be applied only in a subset of the cases that require the installation of packages: you couldn't use it when there's more than one package to install, you couldn't use it when the installation request has to be integrated in a longer, more complex sentence. Besides, writing an installation sentence is not something you have to do several times a day, and in any case it takes about 10 seconds to write it each time, I don't think it would give a noticeable advantage. Last thing - but this is just a personal feeling - it would give me a sense of unnecessary complication, not in the Arch Way :)
This discussion is open, however, more ideas are welcome.
-- Kynikos (talk) 11:59, 24 June 2012 (UTC)

Summary and talk prefer English

Moved from ArchWiki:Reports:

Do we have a rule that says article summary and talk page discussions should preferably be in English? -- Fengchao (talk) 05:03, 3 August 2012 (UTC)

Short answer: no.
Long answer: about discussions, I think we may even elaborate a rule, but it doesn't seem such an important issue on our wiki, we can't enforce rules for everything after all ;) About article summaries, if what you mean are those boxes at the top-right corner of articles, in my opinion we don't even need a rule, it's obvious that they should match the language of the rest of the article; at least this applies to English articles, if there are some language communities which for some reason prefer to keep their summaries in a different language, I guess they can be free to do so.
If there are other people interested in having a rule about the language in talk pages, please add your thoughts here, you may even start a poll to decide whether to enforce English everywhere or have a more complex rule. About me, I'll be fine with whatever comes out of the discussion.
-- Kynikos (talk) 15:08, 5 August 2012 (UTC)
By 'article summary' I meant 'edit summary'. Sorry for terrible terrible wording. (Fengchao moved my random question about style from Reports here) -- Karol (talk) 21:47, 5 August 2012 (UTC)
Eheh now that makes a lot more sense :) I don't know, if somebody can suggest a good formulation for a possible rule, please write it here. -- Kynikos (talk) 09:11, 6 August 2012 (UTC)
What about: "The changes made daily to the articles are bravely checked by dedicated and voluntary patrollers, whom you must help by making sure that all your edits are accompanied by some explanation words in the "Summary" field of the editor page, English is preferd. -- Fengchao (talk) 09:50, 5 October 2012 (UTC)

Daemon operations

I'd like to suggest you / we add wording & style suggestions for systemd daemon operations to Help:Style#Daemon_operations. --User:Stefanwilkens

Agreed, can you start with an example of suggestions? -- Kynikos (talk) 13:58, 3 October 2012 (UTC)
Considering that giving direct examples that can be copy pasted is deprecated, I would suggest something like this:
Use systemctl to enable <servicename> with <servicefile> during boot.
Note: Use systemctl to enable GDM with gdm.service during boot.
Or the more to the point:
<Action> <servicename> with <servicefile> using systemctl.
Note: Start GDM with gdm.service using systemctl.
Note: Enable GDM at boot time with gdm.service using systemctl.
Upon review of this, it seems that we may only have to adjust the references to rc.d and the old DAEMONS array from Help:Style#Daemon_operations and replace it with instructions fitting to systemd. For example:
Daemon operations
  • The standard phrasing is a simple list of the daemons involved, possibly remarking dependencies or conflicts with other daemons, and a link to Daemon.
  • If a required action is not covered in Daemon., it is acceptable to provide an example. Such an example should make use of the systemctl command and provide a listing of the service files involved.
  • The Beginners' Guide and its subpages are the only exceptions to the rules above.
Just suggestions to get the ball rolling, nothing is worse that outdated documentation. --stefanwilkens (talk) 18:25, 14 October 2012 (UTC)

Make discussion pages part more visible

From current status of the Talk pages in Arch wiki, I think lots of people do not know/read these instrucitons before start a topic. Here are some idears to improve the visibility:

  • Move this part out into a seperate page such as Help:Talk.
  • Expand the page to include some examples
  • Add a link to this page on all Talk pages. Do not know whether it is easy to do directly from the MediaWiki. Even if it is hard to do automatically, we can add something such as:
Note: This is discussing page, please read Help:Talk for a guidline. Use -- ~~~~ to sign your edits.

-- Fengchao (talk) 09:27, 17 October 2012 (UTC)