Gentoo Wiki talk:Guidelines/Archive 2

After being marked as completed or closed, the following discussions have been moved from the Gentoo_Wiki_talk:Guidelines article.

Discussions generally occurring between December 2016 to August 2021.

Shortened URLs

Talk status

This discussion is done as of December 30, 2016.

Recently a discussion in #gentoo-wiki (webchat) occurred on shortened URLs. I believe it is in the best interest of the Gentoo community to not permit shortened URLs for a few reasons:

Users have no indication where the destination points. It could be a inappropriate site or some other place they don't want o visit.
The link could be used for tracking purposes. Something that really should't be happening unless the user makes the decision to actually travel to a destination server (meaning there's not a third party in the middle intercepting the request).

In fact, it would seem our spam filter already blocks some shortened URLs. I make the proposition of adding a new section to the Guidelines that will outlaw shortened URLs. --Maffblaster (talk) 20:38, 29 November 2016 (UTC)

I agree with you. Valid shortened URLs should be expanded before adding them to the Gentoo wiki. Fturco (talk) 10:33, 30 November 2016 (UTC)

Same here, no need for shortened URLs in the wiki. --SwifT (talk) 18:57, 30 December 2016 (UTC)

Var element

Talk status

This discussion is done as of December 30, 2016.

I see the <var> element is being used on this wiki for (the names of) configuration variables like "USE", "CONFIG_PROTECT", etc. I'm not sure I like this usage. I think of <var> as marking text that is itself variable (IOW, "replaceable" or "stand-in" text).

Examples:

eselect locale set VALUE (<var> within a <code> element)

man command (<var> within a <kbd> element)

Note that <var> formats text in italics on probably all graphical browsers. This is the convention also used in many published computer books for such stand-in text.

I guess the current usage is probably too entrenched to change at this point, but I'm curious if anyone else shares my concern about this. - dcljr (talk) 23:45, 10 August 2016 (UTC)

The use of <var> can be for both variables themselves (in mathematical expressions or programming) as well as for placeholders, according to w3.org's information. So I don't mind the use of the <var> entity for both.

The formatting as a result of the use of <var> is something that I also find less than optimal, but differentiating variables from the regular text is a good thing. If we find a better expression for such variables, we can easily replace all occurrences of <var>USE</var> with something else later.

I would not appreciate to make it direct links to pages explaining the variable in more detail. We should only link when appropriate, and repeating the same link is also something I dislike (and is not used on wikipedia either for instance).

--SwifT (talk) 09:25, 10 November 2016 (UTC)

I think using the <var> tag to define variables themselves makes sense on our wiki. Once the reader knows italic text means variable, they can more quickly read though the article with the right concept in mind. --Maffblaster (talk) 19:07, 30 December 2016 (UTC)

Update linking section to include 'limited' linking

Talk status

This discussion is done as of May 3, 2017.

I would like to update the linking section a bit (the one currently titled with HTTPS for external links). My suggestion would be to

change the title to "Linking"
expand it to have users only use linking to other articles or resources once (or, in large articles, once per main section)

This is also used by wikipedia.

--SwifT (talk) 09:44, 10 November 2016 (UTC)

Yes, please! I agree wholeheartedly. I probably should have had a discussion here before adding the HTTPS for external links section. :( --Maffblaster (talk) 08:16, 11 November 2016 (UTC)

As of a few seconds ago I have implemented the change. 6 months is long enough to wait for it. :) --Maffblaster (talk) 23:57, 3 May 2017 (UTC)

Use of Cmd versus Invocation template

Talk status

This discussion is done as of November 13, 2017.

Recently, a new set of templates (Invocation and RootInvocation) were added to the Gentoo Wiki to allow expandable output for commands. As an example, consider the following:

user $cat --help

Usage: cat [OPTION]... [FILE]...
Concatenate FILE(s) to standard output.

With no FILE, or when FILE is -, read standard input.

  -A, --show-all           equivalent to -vET
  -b, --number-nonblank    number nonempty output lines, overrides -n
  -e                       equivalent to -vE
  -E, --show-ends          display $ at end of each line
  -n, --number             number all output lines
  -s, --squeeze-blank      suppress repeated empty output lines
  -t                       equivalent to -vT
  -T, --show-tabs          display TAB characters as ^I
  -u                       (ignored)
  -v, --show-nonprinting   use ^ and M- notation, except for LFD and TAB
      --help     display this help and exit
      --version  output version information and exit

Examples:
  cat f - g  Output f's contents, then standard input, then g's contents.
  cat        Copy standard input to standard output.

GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
Full documentation at: <http://www.gnu.org/software/coreutils/cat>
or available locally via: info '(coreutils) cat invocation'

versus

user $cat --help

Usage: cat [OPTION]... [FILE]...
Concatenate FILE(s) to standard output.

With no FILE, or when FILE is -, read standard input.

  -A, --show-all           equivalent to -vET
  -b, --number-nonblank    number nonempty output lines, overrides -n
  -e                       equivalent to -vE
  -E, --show-ends          display $ at end of each line
  -n, --number             number all output lines
  -s, --squeeze-blank      suppress repeated empty output lines
  -t                       equivalent to -vT
  -T, --show-tabs          display TAB characters as ^I
  -u                       (ignored)
  -v, --show-nonprinting   use ^ and M- notation, except for LFD and TAB
      --help     display this help and exit
      --version  output version information and exit

Examples:
  cat f - g  Output f's contents, then standard input, then g's contents.
  cat        Copy standard input to standard output.

GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
Full documentation at: <http://www.gnu.org/software/coreutils/cat>
or available locally via: info '(coreutils) cat invocation'

I have noticed some edits that switch existint Cmd and RootCmd usage to Invocation and RootInvocation. I suggest to add in the guidelines that Invocation and RootInvocation should only be used when the output is very verbose and more exemplary in nature rather than important for the reader to use directly. Its primary purpose (hence the name) is to show command invocation information (the --help output).

Regular commands and their output should, imo, remain with Cmd and RootCmd. One of the reasons I see is that users who might print out an article, or export to PDF or ePub to read elsewhere, will not view the output anymore. So let's save some trees and only use Invocation when it makes sense ;-)

--SwifT (talk) 18:49, 30 December 2016 (UTC)

Agreed. Please implement your suggestions here into the Guidelines. --Maffblaster (talk) 23:59, 3 May 2017 (UTC)

Somewhere on mediawiki site i seen note abot that expand/collapse may not work on some mobile devices. So lets no put important text in command output --Cronolio (talk) 17:02, 8 June 2017 (UTC)

Right, the {{Invocation}} templates are simply to provide users with a quick web-reference of the help output from a command. Users can get the same information locally on their machine after they install the program and run the appropriate invocation for help. I have also added a parameter to the normal {{GenericCmd}}, {{Cmd}}, and {{RootCmd}} templates for expanding/collapsing output (see collapse-output). So now we have options. --Maffblaster (talk) 22:04, 17 July 2017 (UTC)

Closing this discussion as Sven Vermeulen (SwifT) has not responded in 6 months. I think things are in a good state as of now. I'd like the {{Invocation}} templates to still be used for invocation, as we'd be able to explicitly summarize commands with invocations using properties at some point in the future. For all other verbose output the plan is to use {{GenericCmd}}, {{Cmd}}, and {{RootCmd}} with the collapse-output parameter. --Maffblaster (talk) 17:50, 13 November 2017 (UTC)

Bold titles

Talk status

This discussion is done as of July 17, 2017.

The Wikipedia convention of bolding the first appearance of the article's title in the lead section has crept into some of our articles. Should this be encouraged or discouraged? - dcljr (talk) 11:25, 20 February 2017 (UTC)

I honestly don't mind either way. If the article is referencing and acronym, I'd like the acronym described in bold near the beginning of the article. That's my only input on bold text. Kind regards, --Maffblaster (talk) 00:01, 4 May 2017 (UTC)

Just guess, to add a bit more information on what I've been doing recently... I've been using the {{c}} template in the introduction paragraph instead of the bold. I only do this when the intro contains a mention of the command-line executable. I guess if the article doesn't mention the command-line executable bold is being used, which is fine by me. --Maffblaster (talk) 19:15, 15 June 2017 (UTC)

Any feedback from you, Dcljr ? --Maffblaster (talk) 18:39, 17 July 2017 (UTC)

Not really, no. - dcljr (talk) 21:42, 17 July 2017 (UTC)

Package missing

Talk status

This discussion is done as of July 17, 2017.

I missed {{Package| }} on the page --Jonasstein (talk) 06:55, 30 May 2017 (UTC)

There is a line at the end of Block-level layout elements that contains a mention of the {{Package}} template. --Maffblaster (talk) 19:16, 15 June 2017 (UTC)

Since that mention links back to the table of inline templates, I've gone ahead and added {{Package}} to that table. - dcljr (talk) 21:56, 17 July 2017 (UTC)

Update the guidelines to provide links to other gentoo pages in article titles

Talk status

This discussion is done as of January 15, 2019.

Please share your opinion to: Special:Diff/730098/744154

-- Kreyren (talk) 15:02, 27 October 2018 (UTC)

To Brian Evans (Grknight) :
I understand that you agree with the change? Special:Diff/744112/744114 -- Kreyren (talk) 15:06, 27 October 2018 (UTC)

No, sorry, we will not be adding links to section headers or other parts of *Box templates as discussed (from a now deleted article). Closing discussion. --Maffblaster (talk) 07:00, 16 January 2019 (UTC)

The way Discussion is provided so that graphic designers like me can rest in peace

Talk status

This discussion is done as of January 15, 2019.

I suggest to change the way we make discussion to be more effective as `All articles should have "Troubleshooting"` for example meaning syntax likeː

==  TITLE ==
{{talk|open}}

̥Stuff to say and cry about.

--~~~~

'''Discussion Hereː'''
--~~~~

blah.. blah.. blah..

--~~~~

blah.. blah.. blah..

...

(Look at source)

Can we possibly make this into a template? <3 --Kreyren (talk) 21:29, 13 September 2018 (UTC)

No. Not every article needs a troubleshooting section. Sections should be added as appropriate when there is content to actually fill in the section. I believe we discussed this already in #gentoo-wiki (webchat).

To make it extra clear, something should probably be added to the guidelines in order to set expectations correctly. This discussion is a good reminder to do that presently. =) Closing this discussion. --Maffblaster (talk) 07:03, 16 January 2019 (UTC)

All articles should have "Troubleshooting"

Talk status

This discussion is done as of January 15, 2019.

Based on previous experience and end-user feedback gathered from Discord Gentoo i strongly believe that all articles should have "Troubleshooting" section with stub (if less then 3 sub-sections are provided) so that end-users can resolve their issues without the need to visit 3rd party website and which encourage more ppl in contributing to solution.

--Kreyren (talk) 21:11, 13 September 2018 (UTC)

Discussion Hereː

In fact wiki articles have already troubleshooting included f.e. nginx, nfs-utils, tac_plus. Some articles are to short for troubleshooting, but if they get bigger it might get troubleshooting. Some articles do not need a troubleshooting section at all. In my opinion SHOULD HAVE is too much for all articles. Better is MIGHT HAVE, or something like to encourage autors to create a troubleshooting section, but it does not fit to all wiki articles. Troubleshooting should stay optional and is very welcome. Needle (talk) 19:22, 11 October 2018 (UTC)

The blueprints have already troubleshooting included Gentoo_Wiki:Article_Blueprints/Software. Needle (talk) 19:38, 11 October 2018 (UTC)

I agree with needle (Needle) , not all articles need troubleshooting sections. They may be included only when necessary (which is when there's actually common, relevant troubleshooting steps that users encounter that may not be obvious to solve. Troubleshotting sections should be added to articles on an as-needed basis. =) --Maffblaster (talk) 07:13, 16 January 2019 (UTC)

Update Guidelines to avoid paste* websites and other temporary sharing sites

Talk status

This discussion is done.

Based on a recent discussion, I believe it would be helpful to:

Update the Guidelines to instruct contributors to avoid linking to sites that contain temporary locations for text. This includes any paste* services.
Update the Spam filter list to automatically block/prevent links to major certain paste* sites in the Main: namespace.
In my opinion, it is okay to link to source code hosting sites such as GitLab's Snippets or GitHub's Gists if a large amount of code can/should be shared.

Thoughts? --Maffblaster (talk) 17:44, 6 May 2019 (UTC)

No objections here. --Grknight (talk) 19:43, 6 May 2019 (UTC)

I think I'd be cautious about even gitlab snippets and github gists, for similar reasons - they could easily be removed or relocated. It's likely easier to be all-or-nothing on this. The only exception perhaps is Public pastes on User's GL/GH account, where it is slightly closer to the volatility of an ordinary web-page, but I think I'd still be cautious even then.

Would it be possible to operate a simple Gentoo 'pasteznip' service for authenticated wiki users, perhaps, to have a somewhat more stable, controlled place to store text snippets on Gentoo infra? -- veremit (talk) 23:53, 6 May 2019 (UTC)

I have added a new section: Gentoo_Wiki:Guidelines#Avoid_temporary_file_hosting_sites. Michael Everitt (veremit) Sure, it's possible, but outside the scope of this discussion. Infra has enough on their hands, but you could always discuss in the appropriate area (Bugzilla?) --Maffblaster (talk) 23:24, 23 July 2019 (UTC)

Avoid/Use lead-in sentences

Talk status

This discussion is done as of August 2, 2021.

I suggest to keep the text precise and short. Also we should avoid the lead in sentences. Someone who clicked on the link leading to the article knows why she or he is there and does not need another lead in story. --Jonas Stein (talk) 18:17, 11 May 2019 (UTC)

Jonas Stein (Jstein) I wholly agree on the suggestion for precision and terseness. Do you have some examples of articles with lead in sentences that should be reworked? Kind regards, --Maffblaster (talk) 23:26, 23 July 2019 (UTC)

many. "This article covers the recommended method of reporting bugs for Gentoo." on Bugzilla/Guide but nearly half of the pages use redundant lead in stories and are very narrative. --Jonas Stein (talk) 12:03, 3 August 2019 (UTC)

Jonas Stein (Jstein) , now I understand what you mean. Many of these sentences are used for the article description property. This way we can automate the relevant text displayed in the {{See also}} template across many articles. For example, the See also section of the Apache article is generated using Article description property data. Perhaps we could start hiding the lead in sentences when it is unfitting, but still maintain the necessary property data for the template. I am interested in hearing suggestions on how we can maintain auto generation for See also sections, but also avoid redundancy or unnecessary text. --Maffblaster (talk) 18:17, 5 August 2019 (UTC)

I have no received a reply for two years, so I am marking this discussion as closed for the time being. If Jonas wants to pursue it further we can at a future date. Not sure if the explanation as to why we had the article description properties made sense or if it doesn't matter anymore. --Maffblaster (talk) 21:08, 2 August 2021 (UTC)

Forgive My Impetuosity

Talk status

This discussion is done as of August 2, 2021.

I noticed some glaring grammatical errors in this article and plunged right in and corrected them before I even noticed the admonition to discuss all proposed changes before implementing them. Please forgive me. I have been an editor on Wikipedia since 2006, and fixing errors in grammar / idiom / punctuation is just a reflex. --Davidbryant (talk) 20:39, 12 July 2020 (UTC)

I just did the same thing (fixed wording) before I decided to look at this talk page. Do grammar edits fall under the "Please discuss all changes here", or is that just for edits changing the actual content of the guidelines?

xxc3nsoredxx (talk) 22:55, 25 December 2020 (UTC)

You tell me. So far as I can tell, most of the people who laid down the law long ago are long gone. I think it's fairly safe to do what you like when it comes to grammar / punctuation / idiom. There aren't a whole lot of active editors here, so your changes are not likely to be reverted. Merry Christmas! Davidbryant (talk) 23:10, 25 December 2020 (UTC)

I'd say edits involving grammar or punctuation do not need to count toward the need for discussion, however changing the guidelines themselves should be discussed. These guidelines are followed wiki wide, so changing something small affects a lot. Thank you for discussing. --Maffblaster (talk) 21:06, 2 August 2021 (UTC)

Clarification on Cmd vs Invocation (again)

Talk status

This discussion is done as of August 2, 2021.

There was previous discussion about the use of Cmd and Invocation templates, and from my understanding it seems that Invocation is meant to be for including a command's help/usage output. Not just output the author wishes to collapse since the Cmd template has collapse-output=true for that very reason. The "Use case" columns also says, "Displays a user or administrative command's invocation options. These templates should only be used for command invocation." Despite this, the example on the main page uses ls -l as the example for how to use Invocation. Should this be changed to something like the cat --help example from the previous discussion? I think it would better fit the described usage. xxc3nsoredxx (talk) 18:53, 26 December 2020 (UTC)

It's been two months, and since no one has come forth with any objections, I copied the usages mentioned above into the page itself. xxc3nsoredxx (talk) 07:15, 27 February 2021 (UTC)

Sorry. Just saw your discussion. That is a good point. Thanks for merging the change. We'll count this discussion as closed. --Maffblaster (talk) 21:02, 2 August 2021 (UTC)

Gentoo Wiki talk:Guidelines/Archive 2

Contents

Shortened URLs

Var element

Update linking section to include 'limited' linking

Use of Cmd versus Invocation template

Bold titles

Package missing

Update the guidelines to provide links to other gentoo pages in article titles

The way Discussion is provided so that graphic designers like me can rest in peace

All articles should have "Troubleshooting"

See also template and article description properties

Update Guidelines to avoid paste* websites and other temporary sharing sites

Avoid/Use lead-in sentences

Forgive My Impetuosity

Clarification on Cmd vs Invocation (again)