Gentoo Wiki talk:Guidelines

Note
This is a Talk page - please see the documentation about using talk pages. Add newer comments below older ones, sign comments using four tildes (~~~~), and indent successive comments with colons (:). Add new sections at the bottom of the page, under a heading (== ==). Please remember to mark sections as "open for discussion" using {{talk|open}}, so they will show up in the list of open discussions.

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

This article has archive pages for previously completed and/or closed past discussions:

• Gentoo_Wiki_talk:Guidelines/Archive 1
• Gentoo Wiki talk:Guidelines/Archive 2

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 and Microsoft 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), 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)

As a former publisher, a grammar maven, and a seasoned proofreader, I concur wholeheartedly. Why does it take more than a year to implement such a solid suggestion? (PS I hate the passive voice, and so should you.) --Davidbryant (talk) 20:32, 12 July 2020 (UTC)

One thing I can say about this is that it's an easy rule to follow, as it stands. Articles tend to mix voices incoherently over edits, so it seems handy to be able to just tell people "don't write you" :).

-- Ris (talk) 02:18, 19 December 2021 (UTC)

ISO 8601 dates

Talk status

This discussion is done as of 2022-01-19.

MM/DD/YYYY and DD/MM/YYYY dates are easily confused. Could it be an idea to add a section to this page recommending the use of ISO8601 (YYYY-MM-DD) dates on the wiki? This format is unambiguous, and easily recognizable as so - among other advantages.

Remember, with YYYY-MM-DD hh:mm, the largest quantity is always to the left, this is _very nice_ for ordering lists, or when working with dates in code ^^.

-- Ris (talk) 09:01, 19 December 2021 (UTC)

P.Fox (Ris) , I agree with this suggestion. It will be especially useful for to use ISO8601 dates as the standard in the {{Talk}} templates. Unless we see objections here, I would like to incorporate into the wiki by end of year. --Maffblaster (talk) 19:03, 21 December 2021 (UTC)

I second this idea. I already use ISO 8601 dates wherever at all possible. xxc3nsoredxx (talk) 07:09, 15 January 2022 (UTC)

The suggestion has been implemented as of these edits Special:Diff/1043379/1043453. --Maffblaster (talk) 18:34, 19 January 2022 (UTC)

ISO 8601 dates (part 2)

Talk status

This discussion is done as of 2022-01-23.

The ISO 8601 section is currently a subsection of Linking. Wouldn't it be more appropriate to have it as its own section? Well, as its own subsection of Formatting. xxc3nsoredxx (talk) 07:53, 23 January 2022 (UTC)

Good point. It was intended to be a subsection of Formatting, but there was two too many equal signs. Fixed now. Thanks! See Special:Diff/1043453/1044588 --Maffblaster (talk) 07:46, 24 January 2022 (UTC)

Include {{Emerge}} template

Talk status

This discussion is done as of 2022-08-10.

I think it would be nice to include a description of the {{Emerge}} template in the Block-level layout elements section alongside the other command line-likes considering how common/useful it is. xxc3nsoredxx (talk) 05:47, 30 January 2022 (UTC)

Sounds good. -- Ris (talk) 08:35, 28 February 2022 (UTC)

Done as of Special:Diff/1116795. Thanks! --Maffblaster (talk) 18:05, 10 August 2022 (UTC)

Serial comma

Talk status

This discussion is done as of 2022-08-10.

Should we mention to use the serial comma on the wiki ? I think that is how it is usually done here at least... -- Ris (talk) 13:50, 20 February 2022 (UTC)

Although that is mainly used in oxford English (this wiki utilizes American English if I am not mistaken), most of the articles written utilize serial commas as far as I know. Either way, I feel it would be beneficial for people to choose one of them in unison throughout the wiki for better readability. -- Jeff132312342q4323 (talk) 11:13, 28 February 2022 (UTC)

Thanks for noting. The use of serial comma is indeed the standard followed all across on this wiki. Implemented in our "Writing style" section: Special:Diff/1116809 --Maffblaster (talk) 18:24, 10 August 2022 (UTC)

IP documentation prefix usage

Talk status

This discussion is done as of 2022-08-10.

In RFC's RFC3849#section-4, RFC5737#section-3 there is mention of IP documentation prefixes for examples and documentation, these IP prefixes (subnets) are:

• 192.0.2.0/24 TEST-NET-1
• 198.51.100.0/24 TEST-NET-2
• 203.0.113.0/24 TEST-NET-3
• 2001:db8::/32

All above mentioned IP subnets (prefixes) are not allowed to be routed in global internet routing table, and only for the purpose of documentation and showing examples. Actually they are already used in many gentoo wiki articles, mostly by these I have been contributing too, f.e. iproute2. They are used in other documentations to f.e. man syslogd. It would be great if the wiki mentioned and them in the Guidelines. What do you think, is this an option for this wiki? Needle (talk) 03:35, 10 March 2022 (UTC)

Needle , this is a really good find and a fantastic idea that I would like to see implemented. It would be great to see these recommended IP addresses used by our contributors in our various networking articles. That said, the wiki guidelines are not the best place to recommend our contributors to use the IP documentation prefixes. Wiki guidelines focus on style, formatting, and structure, but do not recommended specific content for articles. Perhaps a 'meta' style article focused on networking in the main namespace would be a better place? We don't have such an article yet, so it's open for you to create one. :) --Maffblaster (talk) 18:36, 10 August 2022 (UTC)

Matthew Marchese (Maffblaster) At the moment I would not have a right idea for a separate networking focused 'meta' article. It might be to much and to specific creating a networking blueprint, looking from the gentoo linux perspective. If I get a good idea, and a simple one then I'd create such template probably, atm it is out of scope. Let us leave at that. 11:49, 31 August 2022 (UTC)

Bad link

Talk status

This discussion is done.

Ref in Gentoo_Wiki:Guidelines#Use_lead-in_sentences "Placement of the Topic Sentence, Rochester Institute of Technology, October 10, 2014. Retrieved on January 1st, 2015" links to https://www.rit.edu/ntid/rate/sea/processes/paragraph/process/placement which is 404. Could https://web.archive.org/web/20151026134110/http://www.rit.edu/ntid/rate/sea/processes/paragraph/process/placement replace it ? -- Ris (talk) 10:45, 10 August 2022 (UTC)

Fixed to the correct link in Special:Diff/1116801 --Grknight (talk) 18:14, 10 August 2022 (UTC)

Include "Tip" template

Talk status

This discussion is done as of 2022-08-24.

Should the list of block-level layout elements contain the {{Tip}} template ? -- Ris (talk) 21:34, 19 August 2022 (UTC)

Seems fitting. Added in Special:Diff/1116809/1122016. --Maffblaster (talk) 18:53, 24 August 2022 (UTC)

"Bullet point articles"

Talk status

This discussion is still ongoing.

Some articles seem to get written with the whole contents being presented as bullet point lists, such as Cross_build_environment.

This appears to clash with the writing style of most articles, which seems to me more natural, where steps are simple written as sequential paragraphs. Should we indicate somehow that overuse/exclusive use of bullet points should be avoided?

-- Ris (talk) 10:21, 12 March 2023 (UTC)