Help talk:Style

From ArchWiki
(Redirected from Help talk:Style/Edit summary)
Latest comment: 20 February by Erus Iluvatar in topic Big code blocks

Read this first

Help:Style is an official document of the ArchWiki, and it is actively monitored for malicious, unapproved, or poor quality edits. 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 active supervision 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)

Tip: A way to speed up the addition or modification of style rules is to provide some text that, if approved, can be directly copy-pasted in the guide, just like patches work for bug reports.

Related links

See also or Related in Article Summary?

I think we'd better be coherent whether to keep links, references etc. either in a "See also" section at the bottom of the article, or in one (or more) boxes under the Article Summary at the top right of the article.

See also #Article summary templates.

-- Kynikos 15:15, 21 September 2011 (EDT)

This is more a reminder than other, but I'm starting to like the idea of adding the rule to keep related ArchWiki articles in the Article Summary box only, and external links in See also sections only. Well, this way the "See also" default may even be changed (with bots, don't worry!) to a non-imperative, descriptive title like "Additional resources", "External links" or something like that. -- Kynikos 07:06, 14 December 2011 (EST)
Also remember that many external links in summaries can be found with Special:WhatLinksHere/Template:Article_summary_link. -- Kynikos 07:41, 24 January 2012 (EST)

Advantages of links in See also:

  • There is more space for link descriptions
  • It is likely one will read or skim the article before actively looking for additional reading material. This naturally leaves the reader at the end of the article. It is convenient for the reader in this case if links are at the end of the article. James Eder 00:29, 22 September 2011 (EDT)
  • It seems more common (elsewhere) to have links at the end of articles (when they are not inline with the rest of the text). Following common convention it may be better from a usability perspective. James Eder 00:29, 22 September 2011 (EDT)
    Especially for people used to Wikipedia, which uses the same wiki software. Vadmium 11:12, 26 October 2011 (EDT).
  • I am not sure how much we care about this but it having the links at the end could be more friendly to small form factor screens and screen readers. James Eder 00:29, 22 September 2011 (EDT)
  • As a section, "See also" gets its own TOC entry granting easy access from near the top of the article. Alternatively one may press the END key. James Eder 00:29, 22 September 2011 (EDT)
  • More formatting options here than in summary. Emiralle 13:12, 15 October 2011 (EDT)
  • More inclined to put external, or less closely related stuff here. Emiralle 13:12, 15 October 2011 (EDT)
  • See also section would not be skipped if you start reading the main text sequentially from the top. Vadmium.
  • [add more advantages...]

Advantages of links in Article Summary:

  • Immediately visible
  • Beyond some minor editing inconvenience, is there any real disadvantage of having the most interesting links in both locations? It could be advantageous for the reader to have some links in both locations. James Eder 00:29, 22 September 2011 (EDT)
  • I think putting very closely related links in the summary gives the topic more cohesion, and as James Eder said, they could be included at the bottom as well. Emiralle 13:12, 15 October 2011 (EDT)
  • It would theoretically be more effective in preventing duplication of content within the wiki, as (unexperienced) editors would have a clearer view of the articles where related content could already exist (true especially with series (or "rings") of articles on the same subject). -- Kynikos (talk) 02:46, 29 September 2013 (UTC)Reply[reply]
  • [add more advantages...]

Lists

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)Reply[reply]

> 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)Reply[reply]

Definition

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)Reply[reply]

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)

List of Applications and See also

  1. I suggest for lists like List_of_Applications/Multimedia to use capital letter for the first letter of the description, NO dots at the end (this behaviour seems to be preminent in Wikipedia) and to avoid totally articles ('A ..' is annoying). Is it ok?
  2. In the same list it may be fair to put {{Grp|group}} beside items that have their one.
  3. The See also section should be treated as above lists.

-- Flu (talk) 18:00, 19 May 2013 (UTC)Reply[reply]

I support 1. and 2. except for the dots at the end of descriptions, which I would require instead, since sometimes the App template has long descriptions, even made of several sentences, and including all the puntuation only omitting the final dot would look weird to me.
About 3. I don't understand what you mean, can you be more specific?
However I'm also wondering if these rules should be hosted here (if they refer to the use of Template:App) or in Talk:List of Applications (if they refer only to List of Applications and subpages).
-- Kynikos (talk) 12:23, 26 May 2013 (UTC)Reply[reply]
About 3: I just mean that a section like Aria2#See_also must have capitalized letters and no dots (or whatever the standard would be).
About the hosting place: page like CD_Burning#Burning_CDs_with_a_GUI or Conky#AUR_packages are not directly related to List of Applications, so I think it is worth to host a rule here. Plus this rule would apply also to any other list, like E4rat#Process --Flu (talk) 16:53, 26 May 2013 (UTC)Reply[reply]
Still about 3: I see, usually See-also links have much shorter descriptions, in that case I would apply a no-dot policy. Still open to more opinions though.
Hosting place: a rule about lists of applications would probably best fit in Template:App, also in light of my plans to decentralize style rules in general. A rule about See also sections would instead fit this guide indeed, at least for the moment.
-- Kynikos (talk) 13:17, 28 May 2013 (UTC)Reply[reply]

One link to the package in a paragraph is enough

Do we need multiple links to the same package, wiki article etc. in the same paragraph? I understand that if the article is very long, the links may be used in different sections, but isn't "In the past, Arch used SysVinit as the init process. Now on new installs, Systemd is used by default. Existing SysVinit users are recommended to switch to systemd." with 2 links to SysVinit and 2 links to systemd a bit too much? -- Karol (talk) 23:15, 21 May 2013 (UTC)Reply[reply]

First thing, probably in the title you mean links to articles in general, not only packages, right?
However, I definitely agree, I guess we could extend the rule to the same section or even the whole article, but I'd like to exclude some cases, like "See also" sections (see #Lists of related links), and to make the rule compatible with Help:Style#Official packages and similar.
-- Kynikos (talk) 15:11, 22 May 2013 (UTC)Reply[reply]
Just a reminder: this is affected by Help:Style/Formatting_and_Punctuation#First_instances, not sure if it sould be mentioned directly on Help:Style. -- Lahwaacz (talk) 16:35, 1 September 2013 (UTC)Reply[reply]

git/vcs/source builds

In some article there are source build instruction like Jumanji#Method_2:_From_Source and [3] or AUR git references like [4]. I think they are pointless because:

  • of course you can build application on your own, there is no need to say that.
  • there is plenty of git/patched/vcs variants in AUR. One can decide to install them by their choice.

What about a rule to forbid git/source references unless they are the only chance?

(oh no, another time) -- Flu (talk) 21:15, 2 June 2013 (UTC)Reply[reply]
IMHO 'make && make install' instructions should go.
I have nothing against describing different AUR packages, whether VCS or not. PKGBUILDs are sometimes pretty complex and it's not obvious what's the difference between the various AUR versions of a package - if any.
Please sign your talk page edits Help:Discussion#Join_a_discussion. -- Karol (talk) 20:21, 2 June 2013 (UTC)Reply[reply]
Yes, manual compilation instructions can be removed, but only when an AUR package is available. A rule may be added for this.
No, please don't remove links to "alternative" versions of packages in AUR; treat every AUR package as the others, there are not AUR packages more "official" than others: if they all install the same application, they _can_ (i.e. not _must_) be mentioned in the same article.
-- Kynikos (talk) 05:05, 3 June 2013 (UTC)Reply[reply]
Just mentioning a recent related example, [5], that I consider perfectly reasonable. -- Kynikos (talk) 08:10, 12 June 2013 (UTC)Reply[reply]

Distinguish fragment identifier interwiki links?

Similarly to #Visited_links_color, can we distinguish fragment identifier interwiki links (those written as [[#foo]]) from other interwiki links (generally pointing to some other page)? I find something like [[#PolicyKit authorization|PolicyKit authorization]] [6] kind of confusing, it should be clear that the link points to a section on current page and not to separate page. Possibilities:

  1. prefer [[#foo]] instead of [[#foo|foo]] - this does not solve something like [[#Run daemon|run the daemon]], also note that the fragment is case-sensitive
  2. add some icon (superscript?) in front of/behind the link, I was thinking about the arrow shown in history pages (but without the link to the section)
  3. use some other color

I'd vote for the second, it seems to be the most universal. Or does anybody have some other suggestion?

(Looking at the second link in this post, something similar could be done for links to Wikipedia. In this case, I propose adding superscript W behind the link.)

Sorry if this has already been discussed somewhere else, I don't have the time to search it right now.

-- Lahwaacz (talk) 19:41, 7 October 2013 (UTC)Reply[reply]

Talking of distinguishing links, external https links are not distinguished either:
http
https
Perhaps a bug?
-- Lahwaacz (talk) 06:10, 10 October 2013 (UTC)Reply[reply]
About the little icons next to links, I guess we could do it easily with CSS attribute selectors in the skin files.
About the https icon in particular, it looks it was disabled on purpose for some reason: [7] (line 67) I'd be curious to know why.
Of course to implement all this, a bug report should be opened and very likely patches should be prepared, so if you think you have the time to work on it, the project is at [8] with links to clone the repo. I'd be interested in giving a hand of course :)
-- Kynikos (talk) 09:53, 10 October 2013 (UTC)Reply[reply]
Thanks for pointing me to the right direction, here's the commit about the https links: [9].
Let's see if I can get to this again this weekend...
-- Lahwaacz (talk) 15:05, 10 October 2013 (UTC)Reply[reply]
I sent an email to Pierre about the commit in November and did not receive any reply, so I submitted a bug report: FS#38769 - hopefully it won't be missed. -- Lahwaacz (talk) 16:00, 2 February 2014 (UTC)Reply[reply]
We'll see, I've submitted a patch, but unfortunately wiki bugs, even if easy to fix, have a long life... -- Kynikos (talk) 10:17, 3 February 2014 (UTC)Reply[reply]
Interesting, the https links are now sometimes equipped with a lock icon. It seems that some domains are excluded by the following CSS (which I got with the help of Firebug):
#bodyContent a.external[href^="http://archlinux.org"],
#bodyContent a.external[href^="http://www.archlinux.org"],
#bodyContent a.external[href^="http://wiki.archlinux.org"],
#bodyContent a.external[href^="http://aur.archlinux.org"],
#bodyContent a.external[href^="http://bbs.archlinux.org"],
#bodyContent a.external[href^="http://bugs.archlinux.org"],
#bodyContent a.external[href^="https://archlinux.org"],
#bodyContent a.external[href^="https://www.archlinux.org"],
#bodyContent a.external[href^="https://wiki.archlinux.org"],
#bodyContent a.external[href^="https://aur.archlinux.org"],
#bodyContent a.external[href^="https://bbs.archlinux.org"],
#bodyContent a.external[href^="https://bugs.archlinux.org"] {
    background: none repeat scroll 0 0 rgba(0, 0, 0, 0);
    padding-right: 0;
}
Another interesting thing about this is that I could not find the snippet anywhere in the git...
-- Lahwaacz (talk) 08:44, 14 December 2014 (UTC)Reply[reply]
Eheh maybe you should have looked at Special:RecentChanges :) (still working on it, this may have numerous applications/consequences) -- Kynikos (talk) 08:51, 14 December 2014 (UTC)Reply[reply]
Well that is the last place I would search in, mystery solved. Thanks for testing the workaround, you surely got me on that one. -- Lahwaacz (talk) 09:35, 14 December 2014 (UTC)Reply[reply]

Problem with keyboard keys style

I could use some help with Keyboard Shortcuts:

According to Help:Style#Keyboard_keys, Ctrl+Alt++ should be Ctrl+Alt++, but is that clear enough? (see Keyboard_Shortcuts#X11)

Also, what would be the preferred style for showing multiple shortcuts for some modifier combination?:

  • Alt+.or_
  • Ctrl+Alt++/-
  • Ctrl+Alt+F1, F2, F3, ...

(note: someone used ⇑ Shift on that page, the arrow looks really funny :D )

Edit: the Ctrl+Alt++ shortcut was either dropped from X or is specific to NVIDIA, so I've removed it from the list of standard shortcuts. The only references I found were about 6 years old, the original is probably this.

-- Lahwaacz (talk) 22:22, 16 December 2013 (UTC)Reply[reply]

(I don't wanna know where you've downloaded the font you're using with your browser... XD )
Oh well, even though Ctrl+Alt++ was (luckily?) outdated in that context, that's certainly a big flaw in the style rule... What do we want to do, switch to the Ctrl+Alt++ format? It would invalidate many of the style edits that have been done in the last months, but a bug is a bug ^^ Any better ideas?
About variable combinations, maybe we can just give some examples but leave the choice up to the editor?
-- Kynikos (talk) 13:48, 17 December 2013 (UTC)Reply[reply]
I would not change the rule for just one shortcut (resp. two: Ctrl+Alt+-), converting it back would be really exhausting. If another instance appears, I'd create an exception for it. Or, even better, just link to an external documentation :P
Regarding the second problem I agree with leaving it up to the editor. Examples could be:
  • press Alt+. or Alt+_
  • press Ctrl+Alt+FN to switch to the N-th virtual console
i.e. basically use the full, expanded form or the pseudo-variables.
-- Lahwaacz (talk) 22:12, 18 December 2013 (UTC)Reply[reply]
Well, let's just suspend this discussion until a similar problem is found again then, if ever. I'll think about closing it next time I'll come here to do some general clean up. -- Kynikos (talk) 10:25, 19 December 2013 (UTC)Reply[reply]
Putting spaces around the + character would mitigate some of the confusion in the example Lahwaacz pointed out, but this would unfortunately require a lot of work to bring everything up to a new standard.
-- Jstjohn (talk) 02:32, 11 January 2014 (UTC)Reply[reply]
Um... Ctrl + + doesn't look much clearer than Ctrl++ to me, if one day we'll need to change the rule for keys, we'll better do it the safest way, which probably is Ctrl++, since as you point out it's going to be "a lot of work" in any case. -- Kynikos (talk) 08:51, 12 January 2014 (UTC)Reply[reply]
I'm very late to the party, but NetSysFire suggested the use of Minus/Plus in place of -/+. I think this looks clear enough (see GNOME/Troubleshooting) while also adhering to the existing guidelines. -- Flyingpig (talk) 19:36, 19 April 2021 (UTC)Reply[reply]

kbd tag

Huh, what about [10]? -- Lahwaacz (talk) 08:02, 10 August 2016 (UTC)Reply[reply]

I remember discussing whether to favor the html rendering correctness to the detriment of wiki syntax Simplicity or vice versa, I think it was something about indentation, I don't have the time to search for the discussion but IIRC we decided to keep the wiki syntax simple and be less strict with the html output, so I endorse [11]. – Kynikos (talk) 11:27, 10 August 2016 (UTC)Reply[reply]
Give a suggestion, how about creating Template:Keyboard key (or a shorter name?)? -- Blackteahamburger (talk) 01:32, 13 July 2020 (UTC)Reply[reply]

Grammar errors throughout Help:Style

I've found a large amount of grammar errors throughout Help:Style, and it would be quite tedious to list a before and after for each one here in order to get them fixed. Would it be possible to either temporarily unlock Help:Style for editing (and closely monitor it for unauthorized changes), or if you don't want to unlock it for editing, should I just provide a pastebin with the revised wiki markup that you can copy/paste into the locked page? The downside to the latter option is that one really large change can be a pain to sort through in the history due to the lack of more verbose comments; although, if it's mostly simple grammar fixes, I guess this wouldn't be too big of a problem, as the change comments would likely be quite minimal.

-- Jstjohn (talk) 03:41, 11 January 2014 (UTC)Reply[reply]

It would be awesome if you could fix those errors, it will also be a good chance for me to improve my English: the article is unlocked now. Just make sure not to alter the explicit and implicit meaning of rules, e.g. [12] ;) -- Kynikos (talk) 05:16, 12 January 2014 (UTC)Reply[reply]
I have a general question: what are the rules for using mdash ("—") vs. ndash ("–") in English literature? Is there supposed to be a space around them or not?
(I did not intend to challenge your work, I'm just curious - the rule is very likely to be different from those used in Czech...)
-- Lahwaacz (talk) 20:57, 11 February 2014 (UTC)Reply[reply]
There is not supposed to be a full space around the em dash ("—") or the en dash ("–"). Ideally, the em and en dashes will be surrounded with a hair space, which is just wide enough to put a one pixel space between the dash and the adjacent characters, which makes it easier to read because the dash doesn't look like it's part of an adjacent character. I did not put hair spaces in my edits because I generally find it tedious to do.
As for when you should use the em dash vs. the en dash... the em dash is used for large pauses in speech or for side notes — notice the hair spaces around these em dashes — and the en dash is used for numeric ranges (e.g. 47 – 83).
The hyphen looks similar to the en dash ( - –  ← hyphen on the left, en dash on the right), but the hyphen is only supposed to be used between certain compound adjectives and nouns.
There's also the minus sign ("−"), which looks very much like an en dash ( − –  ← minus sign on the left, en dash on the right). It should only be used in mathematical formulas or when writing negative values (e.g. 47 − 83 = −36)
If you haven't noticed, I'm a bit of a typography geek. haha
-- Jstjohn (talk) 02:02, 13 February 2014 (UTC)Reply[reply]
Thanks for this nice explanation! It is a shame that the wiki markup language does not have special syntax for this punctuation, entering the HTML codes is really PITA. There are some packages for LaTeX that translate "--" into en dash and "---" into em dash. But typographically, TeX is on completely different level than wiki. -- Lahwaacz (talk) 08:08, 13 February 2014 (UTC)Reply[reply]
We could possibly add MediaWiki templates for the em dash and en dash. Adding a template for the minus sign seems like it might be overkill. For example, {{emdash}} or {{em dash}} would output &.#8202;&.mdash;&.#8202; (without the dots, of course)
-- Jstjohn (talk) 23:59, 18 February 2014 (UTC)Reply[reply]
I say let's keep it simple, who would use those templates in practice? They would also go against our decision to e.g. use typewriter quotes instead of typographic, see Help:Style/Formatting_and_Punctuation#Quote_marks. As Lahwaacz mentioned, a wiki is not TeX, it's designed to keep source and rendered text similar, and punctuation templates would reduce readability of source text. MediaWiki takes care of translating source text characters into HTML entities when needed, and in my view we shouldn't try to bypass such feature except when really needed (see also Help:Template#HTML_entities). If you want to use some particular punctuation marks, IMHO you should enter them directly, possibly assigning them as special combinations to your keyboard map. -- Kynikos (talk) 06:00, 19 February 2014 (UTC)Reply[reply]
Regarding source text readability, why not just input the unicode character itself — like this? (Notice that it works also for the hair spaces, though they are not very "hairy" in the source...) -- Lahwaacz (talk) 07:01, 19 February 2014 (UTC)Reply[reply]
I would use those templates. :)
I agree that {{em dash}} would be less readable than a directly-entered "—" character; however, {{em dash}} is a lot more readable than &.#8202;&.mdash;&.#8202; (without the dots), which is why I support the idea. I feel that directly-entered em dashes with the surrounding hair spaces (using the Unicode characters directly) is less maintainable than {{em dash}} because subsequent edits may remove one or both of the hair spaces without editors realizing that they did so.
-- Jstjohn (talk) 01:14, 20 February 2014 (UTC)Reply[reply]
Ok, I admit that to me all this seems overly complicated as in not Simple, however, as Help:Style/Formatting_and_Punctuation#General_rules says, "for cases not covered in this guide, Wikipedia:Wikipedia:Manual of Style is the authority reference", and to me it seems very sensible to stick with that rule instead of attempting to create our own punctuation guides. In particular, Wikipedia:Wikipedia:Manual_of_Style#Punctuating_a_sentence_.28em_or_en_dashes.29 says "do not use spaced em dashes", while they do have a {{spaced ndash}} template, so IMO that's what we should follow. -- Kynikos (talk) 14:21, 20 February 2014 (UTC)Reply[reply]
If we decide for the templates way, which subset of the Wikipedia formatting and function templates should be used on ArchWiki?
I don't like the templates either, this had better be solved upstream (either directly in the parser core or via an extenasion. The only mention of upstream dealing with this I found is this rather old discussion, so it's probably going nowhere. (Extending the parser should not be that hard, a couple of regular expressions should do it for the dashes -- I'm surprised that it's not done yet...)
Suggestions so far: 1) use HTML entities (such as &mdash;), 2) use templates (such as {{em dash}}), 3) use the Unicode characters directly, 4) use some extension (none found yet), 5) drop the typography rules completely (use plain spaced hyphen " - " or commas) -- this could be called "wait for upstream to implement the necessary change" :P
-- Lahwaacz (talk) 16:43, 20 February 2014 (UTC)Reply[reply]
Well, as I've said I'm for 3), with the possible advice of setting key combinations for the most frequent cases (e.g. AltGr + -I'm aware of 1 for the em dash). Just out of curiosity, _personally_ I tend to use ~5) because in my native language all the cases where English requires dashes are covered by commas or parentheses, so I'll be seen rarely, if ever, using dashes in my contributions.
Even if there was an extension to parse "--" and "---", we'd still find resistance for having it installed in our wiki... Maybe upstream they're just waiting for your patch! ;)
About Wikipedia's "formatting and function" templates, for sure we're discarding the "function" ones, and about the others I'd say let's create them one at a time whenever one is needed, but only if method 3) and method 1), in that order, would require too much typing effort for that case.
For completeness' sake, there's also a suggestion 6) to use a (theoretical) external editor that turns "--" and "---" into proper dashes before sending the text to the server, and does the opposite when retrieving a page for editing.
-- Kynikos (talk) 14:38, 21 February 2014 (UTC)Reply[reply]
A little note, the Colemak layout already comes with en dash and em dash respectively preset to AltGr+- and AltGr+Shift+-. -- Kynikos (talk) 13:49, 10 June 2014 (UTC)Reply[reply]

References

Rule suggestion: reference links

First of all, sorry if there is already some similar rule about this, I don't know (yet) what I've forgotten since last year :/

The suggestion:

"When adding troubleshooting sections to new problems, always add reference links into the article, whenever such links are available."

(There is (at least) one implied meaning: "...and not just in the edit summary" :) )

These links will be mostly links to our bug tracker or the forums. The rule should probably include some examples.

The reason behind this is quite obvious: the users (and maintainers) will easily know if the problem is still valid or already fixed.

Finally, some reference links for completeness: [13], [14]

-- Lahwaacz (talk) 21:48, 11 February 2014 (UTC)Reply[reply]

The style guide should be currently freely editable, even though discussing any changes beforehand is a must (so thank you for doing it). You can go ahead and add a few examples, with the only recommendation to be as synthetic as possible, in accordance with the rest of the guide. -- Kynikos (talk) 07:09, 12 February 2014 (UTC)Reply[reply]

Citations and reasoning

Currently we have the following clauses on referencing content:

  • Help:Style#Language register: Remember not only to answer how, but also why. Explanatory information always goes further toward imparting knowledge than does instruction alone.
  • Help:Style#"Known issues" sections: If a bug report exists for the known issue, it is very desirable that you provide a link to it; otherwise, if it does not exist, you should report it yourself, thus increasing the chances that the bug will be fixed.
  • Help:Style#"Troubleshooting" sections: You can also report temporary workarounds for known bugs, but in this case, it is very desirable that you provide a link to the bug report. In case it has not been reported yet, you should report it yourself, thus increasing the chances that the bug will be properly fixed.
  • Help:Style#Hypertext metaphor: If the upstream documentation for the subject of your article is well-written and maintained, prefer just writing Arch-specific adaptations and linking to the official documentation for general information.

With an ever increasing number of edits, as well as the suggested deprecation of ArchWiki:Reports, I think it is time to revisit and generalize this topic. I see following issues with the present set of rules:

  • It assumes editors already know how to properly create and explain content. While linking to bug reports indeed qualifies as a necessity (further motivated in Help:Style#"Troubleshooting") editors should understand to not blindly copy information contained within.
  • The presence of an explanation is alone not enough, it should also provide a clear relation between cause and symptom of the issue at hand.
  • The reference to upstream documentation should be more explicit; for example, only linking to it for "general information" does not imply the understanding needed to write Arch-specific adaptations.

Considering the scope of this rule I would consider a separate section; we can draft it below. Related discussion: ArchWiki_talk:Administrators#Cite_extension -- Alad (talk) 15:04, 7 June 2015 (UTC)Reply[reply]

So, to put it in other words, is your proposal to aggregate all the bits from the 4 linked sections above into a unified section (I guess "Citations and reasoning" would also be the title you have in mind) and expand it with your last 3 points? I do support elaborating on this very important style issue, but wouldn't the new section overlap too much with Help:Style#Hypertext metaphor? Maybe we could more simply expand that, or split its items into subsections? Also I think that it still makes sense to keep reminding to link to bug reports directly in Help:Style#"Known issues" sections and Help:Style#"Troubleshooting" sections, so perhaps those sections should display a link to the new centralized guidelines.
If I haven't interpreted correctly what you had in mind, I'll wait for your initial draft below to understand better.
Kynikos (talk) 03:03, 8 June 2015 (UTC)Reply[reply]
For Troubleshooting, I propose to simply expand Help:Style#Hypertext metaphor with a paragraph on involving upstream, or invonvovled Arch projects. We've been encouraging this for some time, and it seems to works well enough. See below. -- Alad (talk) 20:26, 5 November 2015 (UTC)Reply[reply]
It looks like I forgot what was written above ... -- Alad (talk) 20:30, 5 November 2015 (UTC)Reply[reply]

Positioning of numbered external links

See Help talk:Style/Formatting and punctuation#Positioning of numbered external links.

Lists, colons, indentation

As a continuation of Block quotations, let's clarify our position to multi-line blocks inside lists and indentation (definition lists without definition terms). I have slightly mentioned this in the previous discussion, and I'd like to finish it here.

The markup lists are designed to be simple, and apparently are unsuitable for more complex lists, e.g. with multi-line blocks inside. Wikipedia says: "Do not use lists if a passage is read easily as plain paragraphs." I think that most of the "incorrectness" on Arch wiki comes from disobeying this quote. We should probably recommend using the lists only in simple cases, one or two paragraphs in each item at most (use <br> tags to separate them).

Other common case, unfortunately falling into the non-simple category regarding markup, is that a note or tip is presented inside a list. The "common" syntax has been

* some text
: {{Note|text to note}}

but I've recently seen a number of edits changing it to

* some text {{Note|text to note}}

which is something I don't like, because even though the latter renders correct HTML, it makes the wikitext unreadable. As much as we don't like it, definition lists without definition terms are a feature, and the MediaWiki's manual is full of such tricks. To achieve a fully correct HTML output only with markup syntax, we would need to fix the parser/renderer anyway, so I think we should focus more on wikitext readability.

The only way to achieve correct HTML, is to use HTML tags in wikitext, which brings me to the next problem: [15]. The edit clearly breaks the (future) rule "Do not use lists if a passage is read easily as plain paragraphs.", so the problem is reduced to usage of manual numbering - is it acceptable or do we tolerate HTML tags in such cases?

-- Lahwaacz (talk) 08:11, 29 June 2014 (UTC)Reply[reply]

I agree, look at this page broken by a "Translateme" template inside a list. axper (talk) 08:30, 29 June 2014 (UTC)Reply[reply]
I've used the * some text {{Note|text to note}} trick several times myself, but after reading Lahwaacz's reasoning I won't anymore (when I'll remember), as I agree completely: we should aim for the cleanest source text that results in the wanted appearance of the page. If the generated HTML is not correct it's indeed a problem of MediaWiki, we shouldn't try to work around it.
Yes, we should encourage preferring paragraphs or even subsections to lists with long/complex items. About ordered lists, manual numbering looks quite ugly to me, and I feel the same about mixing HTML and wiki markup: I think most (hopefully all) of the cases where it would be needed are better solved in some other way. For example in the QEMU case reported above, the items of that list don't need to be numbered, bullets or subsections should be used. Another notable example is Arch_packaging_standards#Submitting_packages_to_the_AUR, where bullet points would be more appropriate.
-- Kynikos (talk) 10:49, 30 June 2014 (UTC)Reply[reply]
Maybe we can create a template for items? I mean something like this:
* First item
* Second item
* {{Template_name|
Third item

{{Note|bla-bla}}

Bla-bla-bla
}}
*Fourth item
And there will be a good readability of wikitext as well as correct indentations
-- Kycok (talk) 07:47, 4 July 2014 (UTC)Reply[reply]
This still seems too complicated to me. -- Kynikos (talk) 06:15, 5 July 2014 (UTC)Reply[reply]
I don't think such template is possible, the blank lines would still break the list (test it for Template:bc without <nowiki> tags). All the templates for lists on Wikipedia work the other way, template arguments are turned into list items. See for example wikipedia:Template:Ordered list, but it relies on Lua scripting, which is not available on Arch wiki. -- Lahwaacz (talk) 09:42, 5 July 2014 (UTC)Reply[reply]

See also links

This is a low priority discussion, more of a reminder, however I'd like to recommend a unified style for external links in See also sections, because at the moment the various articles are inconsistent about that. These are some options:

-- Kynikos (talk) 15:36, 1 July 2014 (UTC)Reply[reply]

I vote for the first style. It's compact and IIRC already more popular than the other styles. axper (talk) 16:00, 1 July 2014 (UTC)Reply[reply]
Agreed with axper, +1 to the first style. --Alad (talk) 18:28, 1 July 2014 (UTC)Reply[reply]
I like the first style too. Also, I think this is how the Wikipedia does it. -- Karol (talk) 20:35, 1 July 2014 (UTC)Reply[reply]
I'd prefer the first style too, but I forgot that links in See also section can be accompanied by descriptions, these are some examples of how the style can vary: Core utilities#See also, Secure Shell#See also, Systemd#See also, KDE#See also (funny), Xfce#See also, List of applications#See also. I haven't made up my mind yet. -- Kynikos (talk) 06:48, 5 July 2014 (UTC)Reply[reply]
Meahwhile I've run into a non-standard section in Cursor Themes and I've changed it like this. -- Kynikos (talk) 03:01, 6 July 2014 (UTC)Reply[reply]
+1 for the first style. Yet the examples show how useful a description can be, I vote for making it optional. Having an optional description behind the link looks much neater as well imo, rather than trying to use the link title to transport it in those cases.
Focussing on the links in Systemd#See also: some are indeed a little dated (already), but it would be a pity to loose them. I was wondering for a moment whether it would make sense to foster grouping them, e.g.
But then again there are few cases with that many links and the description can be useful/enough to transport that information too. Some sort of grouping happens automatically by editors keeping relevant links together and ordering most relevant (e.g. project home pages) first.
In my view the whole could be clarified by just appending some examples to Help:Style#.22See_also.22_sections ala:
Examples:
--Indigo (talk) 18:28, 11 August 2014 (UTC)Reply[reply]

OK to put category pages in related articles list?

Recently I made some edits which replaced links to multiple articles with a single link to a category page. That category page contains all those articles.

Are people OK with this? If so, maybe edit Help:Style#Related_articles_box here to instead say:

(change the word "article" to "page") axper (talk) 16:33, 10 July 2014 (UTC)Reply[reply]

My first thought when reading this was "when the article is not included in the given category and it is still relevant, it should be included, otherwise not". On second thought, if the category is relevant enough, the article can be simple put into that category. The big problem is that related articles are at the top and related categories at the bottom.
We can either 1) leave pages at the top and categories at the bottom, 2) include every category into the 'Related articles' box at the top, 3) move the list of categories to the top (how?), 4) move the 'Related articles' box to the bottom (merge into 'See also' again).
Yep, so far I don't like either one of them for some reason or another...
-- Lahwaacz (talk) 19:25, 10 July 2014 (UTC)Reply[reply]
About axper's proposed amendment, I agree, if a group of articles don't have a generic overview (e.g. unlike window managers), then linking to the category that groups them can be useful, if the edited article is not part of such category. Of course if the article itself is part of the category, there's the problem of duplicating the category link in the source text. This reminds me of an old idea of mine that I explained in [16]: translated to the "modern" wiki, it could mean replacing the normal categorization system with a Template:Category to be added to the Related articles box, when present, so that the article gets categorized under some categories, but their links are also shown somehow in the floated box. For example:
Current system
[[Category:Foo]]
[[Category:Bar]]
{{Related articles start}}
{{Related|link}}
{{Related articles end}}

Body
New system
{{Related articles start}}
{{Category|Foo}}
{{Category|Bar}}
{{Related|link}}
{{Related articles end}}

Body
-- Kynikos (talk) 04:33, 12 July 2014 (UTC)Reply[reply]
The problem is that it involves more writing when there are no related articles (it is necessary to add {{Related articles start}} and {{Related articles end}} around the cats). Or would we use the current system for such pages? -- Lahwaacz (talk) 08:40, 12 July 2014 (UTC)Reply[reply]
I was just brainstorming, I'm not sure, maybe we could start using the RA box on every article? Wiki Monkey should have all the libraries needed to automate the migration, both for articles with an RA box and for those without, so the "extra writing" disadvantage wouldn't really apply. -- Kynikos (talk) 05:24, 13 July 2014 (UTC)Reply[reply]

Convention on added/removed text in Hc Templates

I just used the following way to clarify removed/added text in Nautilus#Use delete key to move to trash in Nautilus 3.6 and above:

~/.config/nautilus/accels
; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")
(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")

Is there already a policy on this? --Dettalk 23:29, 10 July 2014 (UTC)Reply[reply]

Nope, there's no policy on that (yet?). Your version is certainly an improvement, compared to the previous -+ system, although in my opinion there's no need to add italic to the stricken line (keep it simple). What I think I've seen around more often, though, is a more verbose:
In ~/.config/nautilus/accels, replace:
; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")
with:
(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")
Your version has the advantage of using Template:hc, thus making it visually clearer that those lines are two versions of the same line, and belong to the same file. The "verbose" version has the advantage of giving clearer written instructions about what has to be done.
Replacing lines doesn't seem to be very frequent in articles, maybe standardizing this would be too much. If we decided to use the "stricken" version, it would probably be worth adding a note in Help:Reading#Append, create, edit and source.
-- Kynikos (talk) 15:30, 11 July 2014 (UTC)Reply[reply]

I disagree with both of the previously suggested styles as neither explains what is changed and why. They're both barely better than telling someone to paste some sed command in their terminal as they rely on the current content of the file (which can change with updates) and they don't immediately convey what needs to be done. My preferred approach depends a lot on the context, but for this case I would do something like:

Create a shortcut to the action <Actions>/DirViewActions/Trash with the key Delete e.g.

~/.config/nautilus/accels
...
(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")
...

This is more broadly informative. If the keyboard shortcut format changes in some way or if the commented line is removed, it will still be clear what needs to be done. --Silverhammermba (talk) 17:28, 8 October 2014 (UTC)Reply[reply]

Questionable edits

There are several kinds of questionable edits made almost regularly to the wiki. They are not breaking any rules (yet?), I just find them useless, counter-productive, or even annoying. I'd like to discuss them to see how others feel. Of course feel free to add a section of your own. -- Lahwaacz (talk) 17:12, 9 August 2014 (UTC)Reply[reply]

Underscores vs. slashes in kernel module names

Example: [17] vs. [18]

From modprobe(8): "there is no difference between _ and - in module names (automatic underscore conversion is performed)". Not only the naming is inconsistent across the wiki, this could lead to edit wars.

-- Lahwaacz (talk) 17:12, 9 August 2014 (UTC)Reply[reply]

Let's just pick one style and go with it. I vote for undescores, since that's how lsmod prints them, consistency would be nice.
I wouldn't consider these 2 edits questionable, rather it's lack of Help:Style rules about this particular subject.
axper (talk) 06:04, 10 August 2014 (UTC)Reply[reply]
+1 for regulating this with underscores as per axper's lsmod argument. -- Kynikos (talk) 09:13, 10 August 2014 (UTC)Reply[reply]

Alphabetical order

Example: [19]

Unless in lists (such as List of applications), alphabetical sorting of sections or other items is useless, I'd even say wrong. Alphabetical sorting is good for finding things, but we have full-text searching nowadays. Even chronological sorting (assuming that new sections are added to the bottom) is more useful for Troubleshooting sections.

Also, have you ever read a book with chapters sorted alphabetically?

-- Lahwaacz (talk) 17:12, 9 August 2014 (UTC)Reply[reply]

I think as long as the sorted sections are equivalent (as in, alphabetical order does not break logical order), you could probably make an argument for both. Should a rule for chronological sorting be found useful, however, I wouldn't object to it. -- Alad (talk) 18:41, 9 August 2014 (UTC)Reply[reply]
Yes, I'd expect a section about a new bug I am looking a solution for to be at the end of the article. axper (talk) 06:20, 10 August 2014 (UTC)Reply[reply]
First, the example edit should have been split (i.e. one section moved at a time).
About the issue, I don't think that alphabetical order can make sense in Troubleshooting or Tips and tricks sections, since the first word of the headings is often incomparable (can be an article, a noun, etc.); chronological order would be better, for example a rule could recommend adding sections at the bottom (or top) of such section groups, unless some similar ones already exist, and in that case I guess keeping similar sections next to each other would be preferable.
-- Kynikos (talk) 09:13, 10 August 2014 (UTC)Reply[reply]
+1, Lahwaacz is right. And one example for keeping similar sections next to each other: GNOME#Extensions -- Kycok (talk) 12:21, 20 August 2014 (UTC)Reply[reply]

Concision

(without example)

Several times recently I was amazed as to how can be a concise article made even more concise. I think that we need more precision over concision. I think that the good wiki pages are usually verbose, as the topic is usually too complex to be described concisely. As tempting as it may be, having an expert making it more concise is not helpful for the majority of others.

-- Lahwaacz (talk) 17:12, 9 August 2014 (UTC)Reply[reply]

I think there's a difference between concision in style and concision in content. Former is a matter of correct writing (convey information that helps understanding, not make it difficult); see [20] for a simple example. Latter should be avoided, and flagged (for example [21]) where appropriate. -- Alad (talk) 18:24, 9 August 2014 (UTC)Reply[reply]
We can indeed put some recommendation like that in the guide, but this is something that the wiki staff will always have to keep an eye on, because experience is the only way to judge, case by case, what's too verbose and what's too concise. -- Kynikos (talk) 09:13, 10 August 2014 (UTC)Reply[reply]
Thanks for this hint. I've never recognized concision as a term and always associated it only with removing of content, either large parts or nuances that might have been intended by the previous editor. Although the language should be concise, let's not take it too far. And especially watch out for the nuances. -- Lahwaacz (talk) 14:08, 10 August 2014 (UTC)Reply[reply]

"as of version X.XX..."

Example: [22]

For some reason users really want to put in when a feature was added to a program. I find this useless because an Arch system always uses the latest version. I think these comments are more appropriate for the talk page or even the user forums. For me the wiki shouldn't be a changelog. I do think it could be appropriate to use when its clear there are issues that are buggy and in progress, but once they are resolved, the note should be removed. Rdeckard (talk) 20:22, 6 March 2016 (UTC)Reply[reply]

I agree that it is useless for features. But I think it is very important for bugs and perhaps even missing features.[23] -- Lahwaacz (talk) 21:46, 6 March 2016 (UTC)Reply[reply]
+1. For [24] see also [25]. Another missing features example is [26]. Such is difficult to track for readers who may have encountered the issue in the past and, in this case, perhaps used a different boot loader just because of it. Perhaps one could say "as of notes" are less useful to keep for missing features in the "Installation" sections, but the further down in the article they are (e.g. in a "troubleshooting" section) the more useful they are for awareness of updates. --Indigo (talk) 09:48, 7 March 2016 (UTC)Reply[reply]
Yes, to generalize, I'd say that "as of" notes are indeed useful next to information that is expected (or maybe reasonably wished/feared) to change in the future. Certainly, added features don't fall in that category, so I agree with the Core utilities, GDM and makepkg edits, but I would undo the Python edit, and, as noted by Indigo, check the SSH keys edit against Talk:SSH_keys#PuTTY_elliptic_curve_support. Since we are in the talk page of the style guide, is there a proposal for the addition of a new rule to discuss? — Kynikos (talk) 07:53, 8 March 2016 (UTC)Reply[reply]
I think a possible style rule could be that adding edits about when changes to a program occurred is mostly appropriate when it's about a bug, or about a product in heavy development that's expected to change soon. Just listing off when features were added to a stable program adds noise and should be avoided. Rdeckard (talk) 02:24, 19 March 2016 (UTC)Reply[reply]
(Welcome to the team, Rdeckard!). Yes, though, take the putty example: it's long a missing feature, putty is not really what one would call heavy development. When the feature finally hits stable, an "as of" might help (an ssh client is an application where I would expect a lot users prefer to use stable and wait). Maybe it is easier to suggest a time-period, i.e. "as of notices" older than (half) a year after a bug or missing feature (which has been tagged as such in the content) has been fixed can safely be removed because of the rolling repos Arch uses.
As for the place to put it: we actually have Help:Style#.22Known issues.22 sections in the guide, but it is rarely used - which is understandable in my view, because mentioning a bug where the related configuration or features are described makes sense. Question is whether we need this style section at all (then an "as of" addition could be added to it), or it should be removed entirely and integrated into the more commonly used Help:Style#.22Troubleshooting.22_sections. (+1)
--Indigo (talk) 07:26, 19 March 2016 (UTC)Reply[reply]
Restarting this discussion because I just did a bunch of "as of" edits. It is a tricky issue because there definitely isn't a simple policy that always applies. That being said I think that most "as of"s should probably go. Here are the main use cases that I've observed:
  1. noting when a feature was added/removed
  2. noting when a default option was changed
  3. noting when a bug was introduced/fixed
  4. noting when the editor last verified the information (workaround was effective, desired feature was missing, etc.)
Number 4 is easy: "as of" is unnecessary. First of all it is redundant since the article history shows when the information was added (and thus verified). Secondly it adds very little value to the reader of the article. If I'm having a problem and a troubleshooting section has a potential solution it doesn't matter if it was working "as of" 100 years ago, I'm going to give it a shot (and then update the article if it no longer works). Lastly it encourages useless edits. If I see an old "as of" and check that it is still the case, does it really add value to the article if I just update the date to show that it still works? Where do we draw the line for that? Should we go around adding "as of" to every single thing that we verify as working? "As of March 3, 2017 sudo can be installed via sudo."
Number 3 is also easy: "as of" is unnecessary. In almost every case it is more useful to simply link to the bug report (ours or upstream). The obvious advantage being that upstream bug reports often include all the information the reader may want: when it was reported, what versions it affects, potential workarounds/solutions, if/when the bug was fixed, etc. Adding "as of" in this case is just sparing the reader an extra click, which goes against the hypertext metaphor.
Number 2 is a little tricky. If it is the case where the option change might require user intervention (e.g. a breaking change in config) then the "as of" is needed. However in most cases I've seen it is still not used well in the article. You'll see something like "As of version X the default is blah ...much later in the article... if you are upgrading from an older version, you may need to...". I think the "as of" is misplaced here: users who installed after the change likely don't care about the new default since they don't have to worry about breakage. In this case the "as of" should be placed in the later section dealing with the issue: "The default is blah ...much later in the article... if you are upgrading from version X, you may need to...". If the default change requires no intervention, I see no need for the "as of": users who run the default likely don't care and users who do not use the defaults are likely unaffected.
Number 1 is also difficult. I think feature removal is slightly easier because if the removal was an intentional design decision by the developers (i.e. not a bug) then the "as of" is not needed. Arch doesn't support users who want to keep old software around, so it is sufficient for the article to simply say that the feature was removed (not when). Because it was an upstream design decision, users reading the article can safely assume that the software will no longer support that feature. For feature addition I think the same logic as number 2 applies. If the new feature might change how upgrading users use the software it should be mentioned in the relevant section.
The only rule of thumb that I think applies in all of these cases is that often an editor adds an "as of" when there is actually something more specific they are trying to communicate: "as of X the default was changed so if you upgrade you have to...", "as of X this feature was removed so instead you may need to install...". By all means keep the the more specific information, ditch the "as of" if possible.
Silverhammermba (talk) 19:14, 3 March 2017 (UTC)Reply[reply]
Very good. One comment: I think a regular case is that someone put a work-around/troubleshooting item into the wiki for a missing feature/default. Later the feature/default is added/changed. I think procedure should be to put a Template:Remove to the workaround first, so that users who might have implemented it get info. Then purge it later. (Obviously, there may be simple cases too.)
Two questions. 1: Do you think we should put a "as of" style suggestion with good/bad examples of usage into the style guide? If yes, where?
Question 2: Look at the above SSH keys#ECDSA example. Coincidentally, the referred to putty package finally gained the feature two weeks ago. How would you handle that, taking into account implementing the feature took a couple of years.
--Indigo (talk) 20:47, 3 March 2017 (UTC)Reply[reply]
I think the "as of" there is needed, but again I think it is misused. Right now it is an example of case 4 i.e. "when I edited this article in March 2016 the feature wasn't there yet". This is redundant and not very useful. A much better "as of" would be to mention that ECDSA support has actually been in the development snapshot since November 2014! That is much more useful. Silverhammermba (talk) 23:19, 3 March 2017 (UTC)Reply[reply]
I agree, somewhat. The "feature not there" info was useful in so far, as there will be users who configure their Arch openssh server (defaulting to ECDSA) but may latter want to connect via another platform's client (i.e. useful to avoid the pitfall with putty as a common client failing to support the server default). Of course it would have been even more useful with the development version info being merged over from the talk page, or the info moved/crosslinked from putty. But ok. My question was for the new status quo: How would you phrase it now, with the new stable version supporting ECDSA? Keep the note with an "as of putty 0.68 (Feb 2017) ECDSA is available", or simply drop it because it does not matter anymore? --Indigo (talk) 02:36, 4 March 2017 (UTC)Reply[reply]
Putty is an exceptional case because there we have to deal with compatibility with other OSes (where the always up-to-date assumption does not apply). So the "as of" there is useful, again as long as it actually mentions when the feature was added.
Also, regarding "as of" in the style guide I think it sufficient to mention the two clear-cut cases: do not use "as of" if you are just noting the last time you personally checked something and do not use "as of" for bug reports, just link to the report itself.Silverhammermba (talk) 18:37, 4 March 2017 (UTC)Reply[reply]
I've handled the Putty example with [27] and [28] I agree it could be done the other way too. --Indigo (talk) 21:29, 6 March 2017 (UTC)Reply[reply]
Great write up above. I'm in agreement that we should tell users not to note the date, time, or program version in their edits if they are just telling us the last time everything worked for them. I also like the idea of encouraging users to link to bug reports instead of giving specific versions. We also need to use the "Known Issues" more often in our articles. -- Rdeckard (talk) 21:11, 4 March 2017 (UTC)Reply[reply]
To make a start with mentioning "as of", I put in [29] and [30] (the latter addition may be a bit sublime). Perhaps you have an idea to make it more prominent or concise along above. --Indigo (talk) 21:29, 6 March 2017 (UTC)Reply[reply]

Some style/grammar guidelines

I have noticed that most, but not all, articles follow these guidelines. I'm somewhat surprised that they are not mentioned here (maybe I just can't find them)? Anyway:

  • Write in second person rather than third. For example "It is recommended that you do foo in order to enable bar on your system" is preferred over "It is recommended that users do foo in order to enable bar on their systems."
  • If possible, do not "recommend" anything. Arch users are expected to read and understand instructions, not follow them blindly; everything on the wiki is implicitly "recommended" and can be ignored by savvy users. If a choice is involved simply explain why users might want to make a choice. So "If you need baz, do foo in order to enable bar on your system." is preferred over "It is recommended that you do foo in order to enable bar on your system". Recommendations are only needed in situations where the choice may be unclear and it is easy to choose poorly (and then a Template:Warning might be in order).
  • Write in an active voice. For example "foo modifies bar" is preferred over "foo is used to modify bar".

Silverhammermba (talk) 20:13, 4 March 2016 (UTC)Reply[reply]

Help:Style#Language register says: "Articles should be written using formal, professional, and concise language." It is certainly possible to make the writing formal and professional enough (at least for this wiki) using second or third person, but recommending to use one over another is too strong, because the best wording usually depends on context. If the whole page is already written in second person, the next modifications usually also use second person to blend in, and vice versa.
The text should be professional, but also feel natural. For example, the Linux Containers page excessively uses "users" to refer to the reader: "Users may use other programs to achieve the same results." Simply using "you" instead of "users" might look better, but I'd write "Other programs may be used to achieve the same results."
As for recommendations, there is nothing wrong with them - they only have to stay objective, expressing personal preference is not allowed (also as per the Language register). In your examples, "It is recommended that you do foo in order to enable bar on your system" would be fine if it was followed by an explanation of why it is recommended.
-- Lahwaacz (talk) 21:22, 4 March 2016 (UTC)Reply[reply]
Actually Linux Containers contains a random mix of second and third person. At a glance you've got "Install the...", "Verify that...", "Users may...", "Users are..." "Disable the...". You even have weird sentences that combine them "For users already using netctl to manage an adapter, simply switch-to it" (I guess you're switching on behalf of the users?). I agree that certain situations require third person, but this is clearly a case of different authors following different writing styles, resulting in strange repeated switching of perspectives. Considering that this problem is present on a lot of articles and we both agree that each article should maintain a consistent perspective, there are a lot of edits to be done. I was just figuring that while we're doing all of these edits, why not make them all consistent across articles?
Let me try to better convey my point about recommendations. I agree that recommendations are fine as long as you explain why, but they are also usually unnecessary if you explain why. For example, Secure Shell says
It is also recommended to disable password logins entirely. This will greatly increase security.
That's fine, but it reads just as well like so:
Disabling password logins entirely greatly increases security.
Greatly increasing security is obviously good, so recommending it doesn't really add anything.
But still, there are certainly exceptions. I suppose that's the case with all of my suggestions: they aren't hard and fast rules, they're more like guidelines that should be kept in mind. If that's not the kind of stuff we want in the style guide, I understand.
Silverhammermba (talk) 06:52, 5 March 2016 (UTC)Reply[reply]
In this case I have to say I generally tend to agree with Silverhammermba: IMHO adding guidelines on these issues would still help resolve possible (minor) edit wars in the future; of course they wouldn't mean that non-complying edits would be rejected, like with all the other rules, but if e.g. two users disagree about the way to phrase something, we have something to resolve the dispute.
About the first problem, though, I tend to prefer third-person or passive-voice writing, and if "Users may use other programs to achieve the same results." doesn't sound as good as when using "You...", I do think that "Other programs could be used to achieve the same results." would sound even better. But I wouldn't generalize, since for example most of the very rules in this guide are better put with an imperative (i.e. second-person) form. For this reason I'd propose to add, in Help:Style#Language register:
  • When editing content, be consistent with the style used in the rest of the article. For example, if the reader is always addressed using the second person, this style should be adopted by the added content; the same goes if third person or passive voice are clearly dominant throughout the article.
And about recommendations, even though I'm surely guilty of giving many in my edits, I agree that a rule like the following could belong in the style guide:
  • When offering a choice among different options (pieces of software, methods to do something, etc.) do not explicitly recommend one over the others, but objectively describe the advantages and disadvantages of each, thus helping the reader to make the best decision for his personal case.
Kynikos (talk) 03:29, 6 March 2016 (UTC)Reply[reply]
About "be consistent with the style...", in my experience w:Mirroring (psychology) is a strong phenomenon among editors, so I'm unsure if an explicit mention is needed in Help:Style.
About "objectively describe", +1 from me. -- Alad (talk) 03:56, 6 March 2016 (UTC)Reply[reply]
Recommending mirroring would avoid the mixtures such as Linux Containers, but also conserve the (bad) style on other pages. Mirroring is a good fallback solution for situations when you have no idea, but I think the guidelines have to state what is right.
Also +1 for the second part about recommendations.
-- Lahwaacz (talk) 13:58, 6 March 2016 (UTC)Reply[reply]
I remember writing this even when we were developing this page 5 years ago: this guide is only in theory aimed at teaching contributors what is the recommended style for the wiki; in practice, only a tiny minority of them reads any part of it, and it is indeed mirroring what accounts for the majority of the style-compliant edits (regarding any style rule, not only these ones). The real, practical aim of this guide is to solve disputes, as I said, and to give an official justification to the style-fixing edits made by the wiki staff and the other proactive users.
That is why explicitly defining what is good and what is wrong, whenever an issue is presented, is always pertinent here. I have added the two new clauses: perhaps that's not the most suitable section, if somebody wants to move them somewhere else, please go ahead, otherwise the next one who agrees can close the discussion :)
Kynikos (talk) 03:20, 7 March 2016 (UTC)Reply[reply]

Example usage

I recently removed a newly added example from Apple Keyboard ([31], [32], see also User_talk:Pypi#Apple_Keyboard). I generally prefer to avoid examples which I feel are covered elsewhere, since they can be prone to bit rot and linking to a page on the topic both encourages understanding and is more robust, however I can't find an "official" stand on this. Have I missed a section explaining proper usage of examples? If not, is there some other reasons for/against that kind of usage of examples? Would it be useful for the style guide to be adjusted to include some "rules of thumb" for dealing with examples? -- Pypi (talk) 21:17, 10 March 2017 (UTC)Reply[reply]

You're right, we're not explicit about examples at the moment: I'd say currently the most related sections are Help:Style#Hypertext metaphor about content centralization, and Help:Style#Package management instructions/Help:Style#systemd units operations about examples only for those specific cases.
Help:Style#Hypertext metaphor allows (obviously) to write Arch-specific adaptations (examples?) of external generic documentation: by analogy (and coherence), this could be seen applicable to topic-specific adaptations (examples?) of instructions which are centrally (and generally) discussed in a "main" article. If we wrote a rule about examples, and perhaps we do need it, it should probably still be quite loose I think, and describe sort of a minimum level of complexity that the adaptation of generic instructions should have to be allowed in an article in addition to a link to the centralized article.
Regarding the specific reverted edit, I tend to agree with you, the example looked quite trivial, so I've tried to instead clarify the paragraph.
Kynikos (talk) 07:48, 11 March 2017 (UTC)Reply[reply]

Long form of uncommon command

We mention as a sub-point about shortening "prefer using the long form of uncommon command options instead of their single-character counterpart."

Then I see sometimes: use -p1 (or --parameter1) and -p2 (or --parameter2)... this easily become quite heavy. Should we mention that if the long form is used, the corresponding short form does not need to be indicated?

Kewl (talk) 20:16, 9 January 2018 (UTC)Reply[reply]

The correct form should be "use -p1/--parameter1 and -p2/--parameter2...". See Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties.... -- nl6720 (talk) 09:33, 10 January 2018 (UTC)Reply[reply]
Ok sounds good, I think both forms should be presented if it adds something, this is what Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties... probably already means with the "have to". -- Kewl (talk) 11:10, 10 January 2018 (UTC)Reply[reply]
Shall we regroup all the comments on parameters in the same section Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties... i.e. moving the point about "prefer using the long form of uncommon command options instead of their single-character counterpart" into Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties... ? I would also add if one form is provided long for uncommon or short for common, it is better to stick to it and it is not necessary to indicate all the possible spelling of an option. -- Kewl (talk) 19:12, 10 January 2018 (UTC)Reply[reply]
Both forms should be presented if you explain the option itself, like in your example. Command line examples usually use short forms except for the uncommon options, but nothing actually forbids the use of long forms.
I don't think moving "prefer using the long form of uncommon command options instead of their single-character counterpart" to Help:Style/Formatting and punctuation would be correct, since it's not about formatting or punctuation. How about simply adding a link in Help:Style#Spelling to Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties.... E.g. "In the same fashion, prefer using the long form of uncommon command options instead of their single-character counterpart. See also Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties...". -- nl6720 (talk) 15:23, 11 January 2018 (UTC)Reply[reply]
It is a good idea it would have helped to know there was also a point about it in Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties... -- Kewl (talk) 16:07, 11 January 2018 (UTC)Reply[reply]
Done. -- nl6720 (talk) 10:03, 13 January 2018 (UTC)Reply[reply]
Great, thanks -- Kewl (talk) 10:05, 13 January 2018 (UTC)Reply[reply]
Thanks guys, do you think we can clarify in a few words when it's ok to represent both the short and long forms of a command option, and explicitly discourage from doing it by default? Or perhaps we should simply discourage it in general? -- Kynikos (talk) 14:37, 13 January 2018 (UTC)Reply[reply]
Yes this was my initial idea I can't imagine cases where this adds much value and this is quite heavy to read. Common we use the short form, uncommon the long form and it is not recommended to indicate the different possible variations of an option nor to switch from one form to another across the page. -- Kewl (talk) 14:50, 13 January 2018 (UTC)Reply[reply]
I see no need to discourage presenting both forms, it's not that much harder to read. I think this should be separated by usage:
  • in text use both (e.g. "... use -v/--verbose for ...")
  • in command line use short options unless they could cause confusion (e.g. efibootmgr -l and -L) and be consistent in using only long or short options
-- nl6720 (talk) 15:55, 13 January 2018 (UTC)Reply[reply]

Transclusion

[Moved from User talk:Lahwaacz#Transclusion -- Kynikos (talk) 05:37, 15 April 2018 (UTC)]Reply[reply]

Special:Diff/517439 "transclusion is useless and visual duplication confusing"

I guess this should be mentioned in Help:Style.

What about Special:Diff/516574? --Larivact (talk) 18:40, 14 April 2018 (UTC)Reply[reply]

IIRC we discussed transclusion at least during the Beginners' Guide merge, and we discarded it in general for lack of arguments in favor of it when compared with simple linking. I'm in favor of adding a style rule to forbid transclusion with the obvious exception for templates. -- Kynikos (talk) 05:37, 15 April 2018 (UTC)Reply[reply]
This also depends on Talk:List of applications#Link subpages instead of transcluding them, otherwise we would need another exception. -- Lahwaacz (talk) 16:19, 23 February 2020 (UTC)Reply[reply]

Categorization of redirects

Larivact has found a good use case for categorizing redirects in Category:Commands so I think we should adjust Help:Style#Redirect pages appropriately. My suggestion:

  • Redirect pages should contain only the redirect code and nothing else. The only exceptions are:
    • Redirect pages with descriptive titles can be categorized to help users navigate to a specific section of a long page. Examples are alias, chown or other pages in Category:Commands. Note that the category of the redirect page should not be same as the category of the target page itself.
    • ...

There may be more exceptions though, I think that most redirects should still be uncategorized.

-- Lahwaacz (talk) 21:54, 23 October 2018 (UTC)Reply[reply]

> Note that the category of the redirect page should not be same as the category of the target page itself.
Awk and Core utilities are both in Category:Commands. --Larivact (talk) 10:11, 24 October 2018 (UTC)Reply[reply]
Practically all commands mentioned in Core utilities currently have redirects in Category:Commands or subcategories.
I agree that multiple redirects to the same target should be allowed to appear in the same category if they have equal relevance and different meanings relative to each other (it would be arbitrary to choose one over the others).
However, if there is already an article that lists (a subset of) the items that belong in a category, what's the disadvantage of requiring to only add that article to the category and forbid adding any redirects to it?
A possible exception is if the main article is not a list of peer items that would belong in its category, but one or more redirects to some of its sections exist, and they are relevant enough to appear alongside the main title in the category.
w:Wikipedia:Redirect#Categorizing_redirect_pages and w:Wikipedia:Categorizing_redirects are easy ways to find inspiration for this style rule.
-- Kynikos (talk) 17:00, 17 November 2018 (UTC)Reply[reply]
It may well be that these categories (those quoted directly below too) are more the exceptions to the rule themselves, not? Sticking to the awk example, [33] scores AWK here as top result, which (curiously;) has not been categorized yet. This non-categorization also makes sense to me, because semantically AWK refers to Category:Programming languages language more than the gnu awk. Now, categorizing any of the two awk redirects into programming languages would be misleading (in my view) for the content at hand in Core utilities#Essentials.
Of course, the categories set for the alias and chown examples above make perfect sense. Maybe change the first bullet sentence like so:
"Redirect pages with descriptive titles can be categorized to help users navigate to a specific section of a long target page, as long as contextual coverage for the redirected term's additional category is warranted. Examples are..."
Elaborating an example what to avoid would make it too complicated I am sure. Can be handled case by case. --Indigo (talk) 22:30, 17 November 2018 (UTC)Reply[reply]
I find your clause hard to understand. We could allow redirects only in "set categories", ie. disallow them in topic categories. --Larivact (talk) 06:27, 18 November 2018 (UTC)Reply[reply]
I meant it the other way - if there is a category which represents some set and a page which lists some elements of this set, then the page does not belong into that category. For example, "Core utilities" is not a command. -- Lahwaacz (talk) 08:50, 18 November 2018 (UTC)Reply[reply]
Thanks for clarifying, that makes way more sense. I put Archiving and compression‎, Core utilities‎ and File permissions and attributes back in Category:Command-line. Now that we have cleared that up, can we add your proposed exception? --Larivact (talk) 15:34, 18 November 2018 (UTC)Reply[reply]
Another point: replace "should not" with "must not" in the last sentence of the bullet.
Otherwise ok with me. --Indigo (talk) 17:16, 18 November 2018 (UTC)Reply[reply]
I'd also drop "with descriptive titles" (which titles are not descriptive?), and at the end I'd also clarify that instead multiple redirects to the same page can be put in the same category, since it doesn't feel obvious to me. -- Kynikos (talk) 15:58, 19 November 2018 (UTC)Reply[reply]
Just mentioning that at least Category:Configuration files is involved too, and redirects have also been added to some subcategories of Category:Commands. -- Kynikos (talk) 13:18, 16 November 2018 (UTC) (Edit: 17:00, 17 November 2018 (UTC))Reply[reply]
I'm late to this discussion, so of course I won't question too much, but in order to understand how to best phrase the new style rule, I'd be curious to read a couple of points that show why this solution is considered better (easier to manage, simpler, etc.) than lists of links in regular articles, e.g. Commands, Configuration files, List of commands, List of configuration files... -- Kynikos (talk) 13:18, 16 November 2018 (UTC)Reply[reply]
Using categories for categorization is the way MediaWiki is designed for. Category indexes are automatically generated meaning that you don't have to edit two pages when you recategorize a redirect. Link pile pages would not integrate as well with category pages, be not as compact (category indexes have a column layout), and could become unsorted. --Larivact (talk) 14:04, 16 November 2018 (UTC)Reply[reply]
Thanks, as I said I won't question further. -- Kynikos (talk) 17:00, 17 November 2018 (UTC)Reply[reply]

dd block size units

GNU Coreutils' dd supports specifying the block size in KiB, MiB, TiB, PiB, EiB, ZiB and YiB.[34]

$ dd if=/dev/zero of=/dev/zero bs=64KiB count=1
1+0 records in
1+0 records out
65536 bytes (66 kB, 64 KiB) copied, 7.583e-05 s, 864 MB/s

Since "KiB" is less ambiguous than "K", I'd like to replace all our bs= usage with *iB. The problem then is BusyBox, it doesn't support it:

$ busybox dd if=/dev/zero of=/dev/zero bs=64KiB count=1
dd: invalid number '64KiB'

Should that stop me from changing wiki articles?

(A related discussion about the units also happened before in User talk:Neven#"M" unit in dd)

-- nl6720 (talk) 14:15, 20 March 2019 (UTC)Reply[reply]

Should the style of redirection be specified?

Help:Style#Redirect pages should this paragraph specify a style, such as using #redirect [[Penguin]] instead of #REDIRECT [[Penguin]] or #redirect: [[Penguin]]? -- Blackteahamburger (talk) 14:41, 30 April 2020 (UTC)Reply[reply]

mw:Help:Redirects#Creating a redirect says that "REDIRECT" is case-insensitive, though there should not be colon after it. I don't know if it's worth adding a style rule just for this. -- nl6720 (talk) 16:23, 30 April 2020 (UTC)Reply[reply]
Some redirection pages use colons at the back. Do I think it should at least stipulate that colons should not be used at the back? -- Blackteahamburger (talk) 23:44, 30 April 2020 (UTC)Reply[reply]
Help:Style#Redirect pages links to Help:Editing#Redirects, personally I've always considered the style used in Help:Editing and related Help pages as the recommended standard throughout the wiki, so much that not long after creating this very page I already started thinking that style rules should have actually been spread and mixed in a series of "Editing" articles by topic, e.g. article structure, usage of templates etc. -- Kynikos (talk) 14:31, 20 June 2020 (UTC)Reply[reply]
Nothing prevents us from reorganizing all the style/editing/etc. guides now :) -- nl6720 (talk) 10:32, 21 June 2020 (UTC)Reply[reply]
See also this old discussion. -- Lahwaacz (talk) 11:05, 21 June 2020 (UTC)Reply[reply]

Should categories use sentence case?

The sentence case information in Help:Style#Title is only for article pages, should categories also follow?

If so, then Help:Style#Category pages should include information about sentence case. -- Blackteahamburger (talk) 09:58, 13 August 2020 (UTC)Reply[reply]

Categories should also use sentence case. We can't link from Help:Style#Category pages to Help:Style#Title since the rule about singular form usage doesn't apply to category pages. I guess we will need to create a separate "Title" subsection in Help:Style#Category pages. -- nl6720 (talk) 10:06, 13 August 2020 (UTC)Reply[reply]
We also have Help:Category and in particular Help:Category#i18n category name already addressing titles. I think that, in agreement with #Should the style of redirection be specified? and related, this could be a good chance to aggregate Category-page style rules there. -- Kynikos (talk) 02:12, 14 August 2020 (UTC)Reply[reply]
Sounds good to me. -- nl6720 (talk) 04:14, 15 August 2020 (UTC)Reply[reply]

Troubleshooting style

The troubleshooting section of many Arch articles are inconsistent and don't follow any established guidelines. A simple guideline would be to list a 1) problem, 2) cause, and 3) solution. For example, the section "Muted audio device" in PulseAudio/Troubleshooting is currently formatted as:

Muted audio device

If one experiences no audio output via any means while using ALSA, attempt to unmute the sound card. To do this, launch alsamixer and make sure each column has a green 00 under it (this can be toggled by pressing m):

 $ alsamixer -c 0

Note

Here are some proposed styles that allow for a sense of consistency and succinctness:

Majamin (talk) 21:48, 22 August 2020 (UTC)Reply[reply]

I don't think that enforcing any style or formatting for troubleshooting sections is realistic. Your suggestions might work for the simplest cases, but most of the troubleshooting content on the wiki is too complex to be formatted into a 3-point list or a 3-column table. Consider e.g. Xorg#Troubleshooting, NVIDIA/Troubleshooting, Network configuration#Troubleshooting, Network configuration/Wireless#Troubleshooting, Network configuration/Wireless#Troubleshooting drivers and firmware, Bluetooth#Troubleshooting. -- Lahwaacz (talk) 11:06, 22 August 2020 (UTC)Reply[reply]
I respectfully disagree. There are some very well written troubleshooting articles in the topics you mentioned, and would be difficult to reformat into the PCS framework (my wording), but I think that the trouble would be worth it. Here is an example of a well-written troubleshooting chart for a car. I believe that we could adopt a similar format to simplify troubleshooting steps. There are times when additional tables and notes are required. Perhaps these could be left to the end of a certain section as notes (similar to note section in Proposals 1 and 2 below). My proposal would make these sections longer, but I believe that the consistent format would ensure ease of reading. With a consistent framework, one could also make the sections more modular. Majamin (talk) 22:09, 22 August 2020 (UTC)Reply[reply]

Style Proposal 1 - Simple problem, cause, solution style

Problem
no audio output
Cause
output devices are muted
Solution
launch alsamixer with alsamixer -c 0` in a console and unmute all devices
Note: alsamixer will not tell you which output device is set as the default. One possible cause of no sound after install is that PulseAudio detects the wrong output device as a default. Install pavucontrol and check if there is any output on the pavucontrol panel when playing a .wav file.

Style Proposal 2 - Table style

Problem Cause Solution
No audio output Output devices are muted launch alsamixer with alsamixer -c 0` in a console and unmute all devices
Note: alsamixer will not tell you which output device is set as the default. One possible cause of no sound after install is that PulseAudio detects the wrong output device as a default. Install pavucontrol and check if there is any output on the pavucontrol panel when playing a .wav file.

Using remarks or footnotes

Sometimes it makes sense to add remarks and other hints.

There are three possible ways to achieve this:

  1. Using Unicode characters[35]. Example page using this (see the table on the right)
  2. A custom wiki plugin
  3. Using <sup></sup> and an ordered list. Example page using this

The first way is problematic because it requires special fonts. The second one is also problematic because it requires time, effort and quite possibly maintenance. It may not be worth it. The third way is the easiest one, it looks better than the Unicode characters and does not require special fonts. Although this does require usage of HTML tags, which is discouraged. But this behavior can not be achieved with mediawiki markup (yet), unfortunately.

NetSysFire (talk) 22:08, 7 September 2020 (UTC)Reply[reply]

I support the third way too: HTML tags are discouraged to the advantage of wiki markup, but they're not forbidden when no simpler alternative is available. -- Kynikos (talk) 05:34, 23 March 2021 (UTC)Reply[reply]
I'm for the third way too. Can you add an example to Help:Style#Formatting or Help:Editing#Formatting? — Lahwaacz (talk) 18:22, 9 September 2023 (UTC)Reply[reply]

systemd user units operations

Help:Style#systemd units operations provides examples of operations of system units, but I think it might also be helpful to provide some examples for operations on systemd/User units as well. Possibly something similar to below:

To have Redshift launched on login, enable the redshift.service or redshift-gtk.service user unit.

-- Flyingpig (talk) 20:41, 22 July 2021 (UTC)Reply[reply]

It's still weird, because the text behind enable does not talk about user units, and user unit talks about the whole concept of a user session manager, not only user units. — Lahwaacz (talk) 07:32, 23 July 2021 (UTC)Reply[reply]
Regarding user unit; what about linking to systemd/User#How it works since it mentions that "other units can be controlled manually with systemctl --user"? A redirect already exists for this too, systemctl --user. Alternatively, I guess systemd#Using units could be changed to mention the --user option for user units, in which case, "user unit" doesn't need to be formatted as a link. -- Flyingpig (talk) 15:01, 23 July 2021 (UTC)Reply[reply]
I think both targets can be improved, then the wording for the operations will not matter (so much) and we can formalize the example. — Lahwaacz (talk) 19:56, 23 July 2021 (UTC)Reply[reply]
Okay, I've made a revision to systemd#Using units that mentions user units. I haven't made a revision to user unit since the other revision mentions systemctl --user. It feels unnecessary to me to use the user unit redirect in the example above following this change. -- Flyingpig (talk) 20:42, 23 July 2021 (UTC)Reply[reply]

Lock keys in "Keyboard keys" section

As mentioned on IRC, Help:Style#Keyboard keys does not mention conventions for lock keys like Caps Lock. Wikipedia prefers Caps Lock to CapsLock (with w:Template:key press), but I use and prefer CapsLock since the former can look weird in key combinations on the ArchWiki due to the space between "Caps" and "Lock". The ArchWiki similarly prefers PageUp to Page Up (or its abbreviation, PgUp). See also w:Page Up.

I think there are about four possible choices for formatting lock keys (when using monospace):

  1. CapsLk (or ScrLk for Scroll Lock)
  2. CapsLock
  3. Caps Lock
  4. Caps_Lock

As mentioned, I prefer the second option (mostly because that's what I typically use). I also prefer it over the fourth option with the underscore since the Caps Lock key on my keyboard is marked as "CapsLock". I don't have an opinion on the first option.

-- Flyingpig (talk) 19:33, 25 August 2021 (UTC)Reply[reply]

Date format guideline

I think that the Style guide should specify a preferred date/time format, particularly for places where dates need to be sortable. Currently I've encountered a mix of YYYY-MM-DD, YYYY.MM.DD, DD.MM.YYYY, MM/YY styles depending on the preference of the author. While it's probably a pointless task to enforce it everywhere, it'd be nice to have a guideline to adhere to. I'd suggest YYYY-MM-DD, as it's ISO 8601 standard and nicely sortable.

My use case at the moment: Laptop/Acer page and family (while these pages have plenty of other unrelated problems, let's focus on the date column right now). Entries are currently timestamped with chaotic formats and to improve usability, I have made the tables sortable and I was going to normalize the dates to make the sorting work correctly. I dropped in to see what Help:Style has to say about it - I wanted to make sure I'd adhere to the norm. Sadly, I found nothing - hence my suggestion to give ISO 8601 the official blessing of the Style guide :)

Zaroth (talk) 10:14, 16 February 2022 (UTC)Reply[reply]

Sounds reasonable and I agree that ISO 8601 date should be preferred for sorting reasons. I guess such a rule would belong in Help:Style#Spelling. -- nl6720 (talk) 09:29, 17 February 2022 (UTC)Reply[reply]
What about Help:Style#Language_register? There's already a bullet point there about avoiding imprecision when referencing time, which could be changed to: Do not use indefinite time references such as "currently", "at the time of writing" or "soon"; replace them with definite expressions such as "as of May 2015" etc. When giving all-numeric dates, use ISO 8601 date format e.g. 2015-05-01, 2019-01. This is especially important in sortable context such as tables. -- Zaroth (talk) 10:57, 17 February 2022 (UTC)Reply[reply]
While the text in Help:Style#Language register will need updating to honor the new rule, I do not think the new rule itself belongs in that section. IMHO it's more of a spelling thing, than a language/wording thing. -- nl6720 (talk) 12:47, 17 February 2022 (UTC)Reply[reply]
Are there other usecases than having dates sortable in tables? Mentioning the ISO in spelling/language register may easily bring up a lot of confusion for general content (e.g. notice the date difference between Template:Dead link and Template:Unsigned, just to name one).
For that reason, I'd find it more useful to add a bullet to Help:Style#Tables, e.g. (based on above):
  • In columns with dates the ISO 8601 date format should be applied, for example 2015-05-01 or 2019-01, to make it sortable.
--Indigo (talk) 13:56, 23 June 2022 (UTC)Reply[reply]
I agree with enforcing ISO to dates in tables, and I agree that adding the rule to Help:Style#Tables is the most pragmatic choice, since it's hard to assess the effects and usefulness of a rule that could be applied in more general terms.
#American vs. British English Usage also refers to this discussion.
-- Kynikos (talk) 15:50, 24 June 2022 (UTC)Reply[reply]
+1 from me too for ISO 8601 at least on table cells, I can't find a reasonable argument for having a unified date format in text form even though I would like one. --Erus Iluvatar (talk) 17:45, 24 June 2022 (UTC)Reply[reply]

Acknowledge "Configuration" and "Usage" as standard sections

The style guide currently does not recognize "Configuration" or "Usage" as standard sections. I propose that these be added, with the following relationship between the sections:

  • Usage information is required to use the software.
  • Configuration information is helpful to customize the software, especially for common use cases.
  • Tips and Tricks information is either advanced, or only applicable for common cases.

I believe that these sections are sufficiently ubiquitous on the wiki. Here are some instances of sections that either literally are Usage sections, or function as one:

Here are some examples of the Configuration section:

Here is some proposed wording for each section. "Tips and tricks" section is a modification of the existing section, but I removed the The various tips and tricks should be organized in subsections bullet as to lax the requirement for the tips and tricks to be related to each other (logically related configuration options are more likely to belong in Configuration).

"Usage" section
  • Usage sections are used for describing how to use the software, and any configuration steps that are required to get started.
"Configuration" section
  • Configuration sections are used for describing how to customize the behavior of software. This info should not be so critical for using the program that it belongs in Usage, but not so advanced or obscure that it belongs in Tips and tricks.
  • There is a higher expectation for hierarchical organization in subsections than with Tips and tricks.
"Tips and tricks" section
  • Tips and tricks sections provide advanced tips or examples of using the software.
  • Use the standard title of Tips and tricks.

Thanks, CodingKoopa (talk) 02:29, 17 March 2022 (UTC)Reply[reply]

I don't really agree that "Usage" should be for mandatory instructions while "Configuration" for optional. For pages about services it would usually be the other way around. -- nl6720 (talk) 08:57, 18 March 2022 (UTC)Reply[reply]
This is a good point. I had dismissed the possibility of this being a problem because of the services that have a usable default configuration (such as Docker#Usage, CUPS#Usage, kinda OpenSSH#Server_usage). I see what you mean now, with services like Pi-hole requiring "Configuration", then "Usage". In fact, I think I'm seeing more occurrences of articles that don't have a "Usage" section at all, since that can happen for services. Thanks, CodingKoopa (talk) 18:43, 18 March 2022 (UTC)Reply[reply]
I would like to restart this subject, I have see a recent revert from User:Lahwaacz converting a "Setup" section back to its original "Configuration" name. While the second is indeed _much_ more common (a search for both terms yields ~800 against ~2000 results), we have not yet explicitly added it to our rules.
I am wondering how to handle the two pages where both "Setup" and "Configuration" are used, namely Mailman and Bcachefs. We also have Linux Containers and Pacman/Package signing where the content of the "Setup" section does not feel like it should be renamed, should we leave them as-is or try to find a more descriptive section title?
--Erus Iluvatar (talk) 12:29, 30 January 2023 (UTC)Reply[reply]

Sub-pages discoverability

As discussed in Special:PermanentLink/741575#Splitting off the Troubleshooting section, it seems splitting some common sections into sub-pages leads to discoverability issues with the way we link to them commonly, i.e. only having a link in the Template:Related at the top of the page.

I propose to have them linked as is done in NVIDIA#Tips and tricks and NVIDIA#Troubleshooting.

This would also avoid new sections like Advanced Linux Sound Architecture#Intel Cannon Lake PCH cAVS (eg. HP ZBook 15 G6) which belongs to Advanced Linux Sound Architecture/Troubleshooting#Hardware and Cards.

--Erus Iluvatar (talk) 18:30, 15 August 2022 (UTC)Reply[reply]

CLI prompts for Windows

In e.g System time#UTC in Microsoft Windows, the user is expected to run a command on Windows, but it is missing the shell prompt C:\.

I discussed this in our IRC. Erus Iluvatar mentioned USB flash installation medium#Using flashnul and said "But IMO in that page the C:\ part of the prompt provides no relevant information to readers. On the other hand, only having ">" feels weird as it could be confused with a shell redirection at first glance".

My take on this is that having a C:\ prompt would be very intuitive and one can see what to run where at a glance. Thoughts? NetSysFire (talk) 05:27, 22 January 2024 (UTC)Reply[reply]

Yep, I can confirm my final conclusion was using C:\> in full :)
-- Erus Iluvatar (talk) 06:36, 22 January 2024 (UTC)Reply[reply]
I agree with using C:\> (note that there's no space after > unlike Help:Style#Command line text), but it feels wrong to me to add a style rule about Windows prompts. -- nl6720 (talk) 10:07, 22 January 2024 (UTC)Reply[reply]

Big code blocks

[Moved to Help talk:Editing#Big code blocks. -- Erus Iluvatar (talk) 07:53, 20 February 2024 (UTC)]Reply[reply]