Gentoo Wiki talk:Guidelines

Please discuss all changes here before making any changes to the Guidelines article.

Go to this article's archive sub-article to see previous completed discussions.

==

All articles should have "Troubleshooting"
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ː

Usage of KernelBox
Isn't it better to provide path instead of using ? Based on my experience it's very missleading. I would prefer to use this version instead https://imgur.com/a/emX22W2 in one line of text with "some" formatting to differenciate it for end-user.

Possibly like?

NOTE: won't display with `[=y]` parameter. --Kreyren (talk) 03:09, 29 August 2018 (UTC)

Discussion:


 * Long time ago only was discussion about do write an extension for mediawiki to show setting for different versions of kernel. And maybe also do show in config mode like


 * If you able for this, please do it. --Cronolio (talk) 05:54, 29 August 2018 (UTC)

--Kreyren (talk) 13:25, 3 September 2018 (UTC)

Shouldn't be an issue, but i need the permission from gentoo dev.

Shortened URLs
Recently a discussion in 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: 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)
 * 1) Users have no indication where the destination points. It could be a inappropriate site or some other place they don't want o visit.
 * 2) 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).


 * 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
I see the 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 as marking text that is itself variable (IOW, "replaceable" or "stand-in" text).

Examples:
 * ( within a 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 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
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
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:

versus

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  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 ). So now we have options. --Maffblaster (talk) 22:04, 17 July 2017 (UTC)


 * Closing this discussion as 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   parameter. --Maffblaster (talk) 17:50, 13 November 2017 (UTC)

Bold titles
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, ? --Maffblaster (talk) 18:39, 17 July 2017 (UTC)


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

Package missing
I missed  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)

See also template and article description properties
Using SMW properties to define the Article description property in various articles, I've created a new See also template that can be used to reduce the need to re-describe every article summary in the See also sections of the articles. Any objections to mentioning the See also template and defining how to set the article description property here? Kind regards, --Maffblaster (talk) 18:38, 17 July 2017 (UTC)


 * Bump. Any comments? My only concern is how the See also template will play out with translations. --Maffblaster (talk) 17:46, 13 November 2017 (UTC)


 * I don't have any objections to describing this template in the guidelines. Please do. (I can't say anything about translations.) - dcljr (talk) 05:09, 4 December 2017 (UTC)


 * If any problem with template understanding


 * {{#if: {{{1|}}}
 * if pagename is set (for example )
 * | {{#ifexist: {{{1}}}{{Langswitch}}
 * # Langswitch depend on subpagename, where it's called. For example on page  subpagename is   and  langswitch will return  . The same with other translated pages. If langswitch is called from native english page (without any subpages), he return nothing (  in the end).
 * # Assuming that this called from any  page ...
 * if  page is exist
 * | {{{1}}} — {{#show:{{{1}}}{{Langswitch}} | ?Article description= }}
 * # show  as link and   as name of the link —   description
 * #  required for pages if they started from   like
 * | {{{1}}} — {{#show:{{{1}}} | ?Article description= }} }}
 * # else (when  does not exist) show
 * |{{Error|See also|Anonymous parameter}}
 * # else (when pagename is not set) show error


 * Writers should set name of the page in seealso template and add description tag if no exist yet. Translators can copy&paste seealso when doing translation.
 * I know only one issue with translations. In case when translated page is exist, but no any article description there (no marked for translation or fuzzy bot don't merge new edits) it's will show  (empty description) --Cronolio (talk) 20:57, 29 March 2018 (UTC)