Gentoo Wiki talk:Guidelines

From Gentoo Wiki
Jump to: navigation, search
Note
This is a talk page. Please add newer comments below older ones, and sign your comments using four tildes (~~~~). When adding a new section (at the bottom of the page), please mark it as "open for discussion" by using {{talk|open}} so it will show up in the list of open discussions.

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.

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:

  1. Update the Guidelines to instruct contributors to avoid linking to sites that contain temporary locations for text. This includes any paste* services.
  2. Update the Spam filter list to automatically block/prevent links to major certain paste* sites in the Main: namespace.
  3. 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)

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: https://wiki.gentoo.org/index.php?title=Gentoo_Wiki:Guidelines&diff=744154&oldid=730098&rcid=&curid=1325

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

To Brian Evans (Grknight) :
I understand that you agree with the change? https://wiki.gentoo.org/index.php?title=NVIDIA/Optimus&diff=744114&oldid=744112&rcid=&curid=42197 -- 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 here. 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.
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 , 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)

Heading text

Shortened URLs

Talk status
This discussion is done.

Recently a discussion in #gentoo-wiki 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:

  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).

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)

See also template and article description properties

Talk status
This discussion is done as of January 15, 2019.

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 bla)
| {{#ifexist: {{{1}}}{{Langswitch}}
# Langswitch depend on subpagename, where it's called. For example on page bla/de subpagename is de and langswitch will return /de. The same with other translated pages. If langswitch is called from native english page (without any subpages), he return nothing (#default = in the end).
# Assuming that this called from any de page ...
if bla/de page is exist
| [[:{{{1}}}{{Langswitch}}|{{{1}}}]] — {{#show:{{{1}}}{{Langswitch}} | ?Article description= }}
# show bla/de as link and bla as name of the link — bla/de description
# : required for pages if they started from / like /etc/portage/make.conf
| [[:{{{1}}}]] — {{#show:{{{1}}} | ?Article description= }} }}
# else (when bla/de does not exist) show bla — bla description
|{{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 bla — (empty description) --Cronolio (talk) 20:57, 29 March 2018 (UTC)

It has been a while and no objectives. As of July, 2018 the {{See also}} template supports translations so I really no longer see potential limitations/head aches for our translations teams. Thanks for the feedback, gentlemen. Adding it to the Guidelines... --Maffblaster (talk) 07:18, 16 January 2019 (UTC)

Passive voice, imperatives, and you/your

Talk status
This discussion is still ongoing.

I can understand why the third person passive voice is recommended for (non-persona-driven) wiki articles, since there will (hopefully!) be many contributors maintaining the content over time, so there is no single author "I" (and using "we" sounds stuffy).

However, as the active voice imperative mood is also implicitly recommended (for install instructions etc), I'm not sure the admonition to avoid "you" (and, by extension "your") quite follows.

If, for example, the instruction "Now install the package foo:" is given, this is active voice, with an implied subject (the reader = "you") (otherwise, we'd have to say "Let the package foo now be installed:" or similar, imperative passive voice). And given that the implied pronoun is "you", it then feels unnatural (to me, anyhow) not to be able subsequently to say things like "Now, if bar is already installed on your system..." ("your" = possessive determiner). FWIW, Google[1] and Microsoft[2] disallow (aiui) "I/we", but permit "you"/"your"/"yours" in their instructional material.

In other words, since the content in this Wiki consists mostly of instructions (rather than e.g. presentations of scientific results), quite a lot of it (following current guidelines) will end up not being in third-person passive voice at all, but in (implied second-person) active imperative. As such, I'd argue that second-person writing (used sparingly) shouldn't be discouraged, or necessarily flagged up as a candidate for editor rewrites. I do agree that "you" should generally be omitted from imperatives themselves (for reasons of brevity: "Now install foo:" scans easier than "Now you should install foo:").

Perhaps then (following the TechnicalWriter Wiki[3]), it might be a little clearer to say:

  1. Descriptive writing should be in the third-person, active passive voice, indicative
  2. Instructions should be in the second person, active voice, imperative

and that where e.g. possessive determiners ("your system" etc) follow from the second, they are permissible? --Sakaki (talk) 16:30, 27 April 2019 (UTC)

References

  1. Google Developer Documentation Style Guide: "Language and grammar: Second person". Retrieved 27th April 2019.
  2. Microsoft Style Guide: "Grammar and parts of speech: Person". Retrieved 27th April 2019.
  3. TechnicalWriter Wiki: "Using the correct language". Retrieved 27th April 2019.

Avoid/Use lead-in sentences

Talk status
This discussion is still ongoing.

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 https://wiki.gentoo.org/wiki/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)