Gentoo Wiki talk:Guidelines
Before creating a discussion or leaving a comment, please read about using talk pages. To create a new discussion, click here. Comments on an existing discussion should be signed using
~~~~:
A comment [[User:Larry|Larry]] 13:52, 13 May 2024 (UTC) : A reply [[User:Sally|Sally]] 08:27, 5 November 2024 (UTC) :: Your reply ~~~~
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:
Passive voice, imperatives, and you/your
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:
- Descriptive writing should be in the third-person,
activepassive voice, indicative - 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" :).
- As someone who wrote documentation professionally for the the best part of a decade I agree with the sentiment expressed here. The current wiki guidelines result in stilted writing and gate 'compliant' wiki editing behind an assumed level of English competence. I'm not going to point out specific examples (because that would be mean-spirited), but even contributors with English as their first language can absolutely ruin the flow of an article when attempting to write within these artificial restrictions.
- The OP is right. That no action has yet been taken on this point is discouraging to people like me who care about clear discourse and want to help raise Gentoo's documentation to this ideal. For instance, the first sentence of the second paragraph says, "Third person and passive voice are preferred[1]; we argue these sound more professional and objective; especially for technical instructions, which is the majority of the wiki's content." What's ironic here is the linked page is explicit in disapproving of the use of third-person. What's more, the reason stated is that it encourages the passive voice. The author stresses that both are not ideal in technical documentation (nor is the passive appropriate most anywhere else: see Steven Pinker's The Sense of Style for a clear explanation of when it works). Still, the irony is further compounded when we come to the second sentence in the third paragraph which says, "For instance, do not use "You should now install the package" instead use "Next, install the package"". The suggested latter directive is the second-person, the very thing we're being told not to use.
- Bent Fingers (talk) 00:27, 17 October 2023 (UTC)
- This issue has been sitting in front of us for long enough that it's started to smell.
- I don't disagree with the criticism of our current guidance, however the actual wiki style in practice is mostly fine.
- I'd like to suggest (showing my biases here) mining the Australian Government style guide to come up with some more comprehensive guidance that we can summarise for users.
- https://www.stylemanual.gov.au/writing-and-designing-content/clear-language-and-writing-style
- https://www.stylemanual.gov.au/writing-and-designing-content/clear-language-and-writing-style/voice-and-tone
- https://www.stylemanual.gov.au/writing-and-designing-content/clear-language-and-writing-style/plain-language-and-word-choice
- Mining the above section will probably get us into to a better position than we are now without needing to rely on a mailing list post that's old enough to drink in most countries.
- Note
This would be a great opportunity to implement and employ the MediaWiki citation templates
- I'm happy to volunteer to do the work, but it _will_ reflect my biases and time spent writing user documentation for a living.
ISO 8601 dates
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)
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
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)
- Done as of Special:Diff/1116795. Thanks! --Maffblaster (talk) 18:05, 10 August 2022 (UTC)
Serial comma
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
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 (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
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
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"
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)
- I'm generally in favour of what you've described but we do need to make sure that we aren't encouraging people to write pages of prose for the sake of it. If you only need a short line between instruction and output examples you shouldn't need to be more verbose than is required to get the step across (see MangoPi_MQ-Pro for an example of where I think that's appropriate).
- I don't think that "bullet points" (an unordered list) is appropriate however - if a contributor wishes to use this style and put it in some sort of 'list' it needs to be an ordered list - (1, 2, 3; a, b, c). The wiki guidelines should be reflect that an unordered list is for when the order doesn't matter; it is not suitable for conveying a sequence of instructions.
Correction of a very minor typo
On the section 1.1, "Avoid first and second person writing", if I am not mistaken the word "encourage" on the 4th paragraph should have been passive instead. "Contributors are encourage to rewrite these sections as..." --> "Contributors are encouraged to rewrite these sections as..."
I feel weird writing an entire paragraph here about this, but the article is not editable. Hopefully, I am doing the right thing. Cheers. Kresni (talk) 16:00, 29 April 2023 (UTC)
- Yes, you did the right thing. Sorry it look a bit to implement the fix. We have the page locked down because of its importance. We've historically had edits without discussion in the past, so we prevented that from occurring again by tightening down security. See Special:Diff/1251645/1251646. --Maffblaster (talk) 01:29, 16 July 2023 (UTC)
Policy for illustrations
"A picture is worth a thousand words". What are the guidelines in that case? Use an editable vectorial format (like SVG) / lossless raster format like PNG? I guess there are IP/licensing issues. --Admnd (talk) 17:31, 6 May 2023 (UTC)
- I don't know that there are any particular guidelines for file formats, spare from what the wiki supports. Are you planning on illustrating something in particular?
- Licensing is very important, we allow only PD, and some CC and GNU licenses. They are listed in a drop down menu on the upload page. You must have permission to release under the specified license.
- I would agree with P.Fox (Ris) , we already have guidelines around licensing for file uploads (see the "Upload policy" box on the special file upload page. This would cover illustrations, so I don't think it's really necessary to go beyond what's specified there. Diagrams or images are not required in articles, but can be used to illustrate as necessary (see Emerge for an example). The wiki will accept a variety of image formats; SVG and PNG are both included. A free license must be used, otherwise we will remove the file. Hope this helps! --Maffblaster (talk) 01:37, 16 July 2023 (UTC)
US English Guideline
Hi All,
Gentoo represents a diverse global community, cherishing valuable contributors from various parts of the world. So, it begs the question: why, in 2023, do our wiki guidelines explicitly favor one regional variant of English over others?
The mandatory use of US English has become a source of immense frustration for me, particularly when well-intentioned contributors alter 's' to 'z' in a direct quote from a Non-US-English source. This predicament forces me to juggle between US and Non-US English within an article, alternating between quotes and the main text. As a result, I often find myself disregarding these guidelines entirely, which inevitably leads to conflicts over edits in the future.
It appears that we inadvertently imply that Americans, Canadians, and those unfortunate souls educated in this particular variant of the English language are somehow less competent than their international counterparts in handling the presence of an unexpected number of 'u's in words.
My proposal for the Gentoo Wiki is to adopt a policy similar to that of Wikipedia, where no preference is given to any specific regional variant of English. The choice of English style should depend on the contributor's comfort, the existing content of the article, and what makes the most sense in context.
For instance, it should be acceptable to ensure consistency in articles quoting non-US-English sources if you are already editing them. However, it is not acceptable to make such changes arbitrarily without a valid reason. Going down that path would only lead to chaos and conflicts over edits.
Kangie (talk) 23:29, 7 June 2023 (UTC)
- Matt Jolly (Kangie) , thank you for your thoughts and the effort you pour into making Gentoo documentation better! In no way do we mean to imply or suggest that British English is inferior in any way to its American cousin. With that said, I do not find reason to change our existing guideline to encourage inconsistency of English dialects/versions between articles on the wiki.
- You do raise a valid concern regarding the use of citations from an English variant other than American English. I have added the following change as a way to help provide additional guidance for citations. It was never our goal to encourage editors to change the text between the quotes of a cited source. I hope you find this change helpful! See Special:Diff/1251646/1251649. Kind regards, --Maffblaster (talk) 02:01, 16 July 2023 (UTC)
Typo
- it provides a proposal that can be merged as is,
- that proposal has been unchanged and uncontested for 30 days, and
- all participants have reached a consensus.
To display a command running with superuser privilege (can optionally includes command output)
Should be:
To display a command running with superuser privilege (can optionally include command output)
Waldo Lemmer (talk) 19:11, 27 March 2024 (UTC)
Another typo
- it provides a proposal that can be merged as is,
- that proposal has been unchanged and uncontested for 30 days, and
- all participants have reached a consensus.
Note
While the various inline formatting templates like C, Keyword, Path, and Package may freely be used inside of the Note, Important, or Warning templates. They should never be used inside of Cmd, RootCmd, Emerge, Invocation, or any other *Box templates.
Should be one sentence:
While the various inline formatting templates like C, Keyword, Path, and Package may freely be used inside of the Note, Important, or Warning templates, they should never be used inside of Cmd, RootCmd, Emerge, Invocation, or any other *Box templates.
Contradicting reference
- it provides a proposal that can be merged as is,
- that proposal has been unchanged and uncontested for 30 days, and
- all participants have reached a consensus.
Section Avoid first and second person writing has a sentence that contradicts its reference:
Third person and passive voice are preferred[4]
The referenced page discourages the use of third person and encourages the use of second person pronouns.
I propose simply removing that reference
— Waldo Lemmer 12:10, 19 April 2024 (UTC)
Typo 3
- it provides a proposal that can be merged as is,
- that proposal has been unchanged and uncontested for 30 days, and
- all participants have reached a consensus.
This is the title of section Use ISO 8601 for date and time representatio
Use ISO 8601 for date and time representatio
— Waldo Lemmer 12:38, 19 April 2024 (UTC)
<syntaxhighlight>
As mentioned in section Block-level layout elements, HTML and wikitext in {{CodeBox}} should be avoided. This is due to how {{PreBox}} passes arguments to the underlying <syntaxhighlight> element. An alternative option is to use <syntaxhighlight> directly.
I propose adding this after the last row in that table:
| <syntaxhighlight> | To display HTML and wiki markup (with optional syntax highlighting). | == Installation ==
[[Category:User collaboration requests]]
|
— Waldo Lemmer 08:24, 1 May 2024 (UTC)
- This is a reasonable suggestion and would be an improvement so that we can highlight these two languages. It has been implemented into the table. Thank you! --Maffblaster (talk) 22:44, 4 May 2024 (UTC)
KEntry
- it provides a proposal that can be merged as is,
- that proposal has been unchanged and uncontested for 30 days, and
- all participants have reached a consensus.
The page currently explains {{KernelBox}}'s usage as follows:
| Template | Use case | Example |
|---|---|---|
| {{KernelBox}} | To display details on kernel configuration. The content should make it obvious to users how to reach the particular configuration settings in, say, menuconfig. Do not use the short-hand CONFIG_FOOBAR notation. Note: HTML and wiki markup (including links) in this template is to be avoided. |
KERNEL Enabling evdev Device Drivers --->
Input device support --->
<*> Event interface
|
After some discussion with P.Fox (Ris) and (I think) Alexis (Flexibeast) , we all agree that tooltips with CONFIG_ are helpful and that {{KEntry}} looks good. Thus, I propose the following:
| Template | Use case | Example |
|---|---|---|
| {{KEntry}} | Used for kernel configuration entries and their respective CONFIG_ variables together with {{KernelBox}} (see below) | Event interface Search for <code>CONFIG_INPUT_EVDEV</code> to find this item. |
| {{KernelBox}} | To display details on kernel configuration. The content should make it obvious to users how to reach the particular configuration settings in, say, menuconfig. Note: {{KernelBox|1=}} should be used for the header. The text below it should be preformatted.
|
KERNEL Enabling evdev
Device Drivers --->
Input device support --->
<*> Event interface Search for <code>CONFIG_INPUT_EVDEV</code> to find this item.
|
I will update the documentation for {{KernelBox}} if this proposal is merged.
— Waldo Lemmer 07:37, 19 May 2024 (UTC)
- The documentation for {{KernelBox}} has been updated. I see other editors on the wiki have started using {{KEntry}} as well.
- — Waldo Lemmer 15:37, 17 June 2024 (UTC)
Typo in passage Documenting a package or software title
This sentence right before the end has a typo:
It is good prictice to split sections up, so that their subsections each cover just one operation;
It is good practice to split sections up, so that their subsections each cover just one operation;
SigHunter (talk) 13:08, 31 August 2024 (UTC)
Remove superfluous "to"
On two similar occasions there is an additional "to" that should be removed:
It is useful to add a short description of each link, and as with "See also" sections it can be helpful to add a short sentence to to inform the user how each element is related to the current article, or why it may be of interest.
It is useful to add a short description of each link, and as with "See also" sections it can be helpful to add a short sentence to inform the user how each element is related to the current article, or why it may be of interest.
It is useful to add a short description of each link, and as with "See also" sections it can be helpful to add a short sentence to to inform the user how each element is related to the current article, or why it may be of interest.
It is useful to add a short description of each link, and as with "See also" sections it can be helpful to add a short sentence to inform the user how each element is related to the current article, or why it may be of interest.
SigHunter (talk) 13:52, 31 August 2024 (UTC)
Missing "are" in References section
There's a verb missing, likely an "are":
Once the appropriate <ref> tags are in place, these sections automatically generated
Once the appropriate <ref> tags are in place, these sections are automatically generated
SigHunter (talk) 14:12, 23 September 2024 (UTC)
Suggestion: Add policy re. capitalization
i would like a policy around capitalization, along the lines of:
Whether or not the name of a program should be capitalized should reflect the program's official documentation, unless referring to the specific binary for that program. Thus, for example: "To start Bash, run the bash command; to start fish, run the fish command."
-- Flexibeast (talk) 04:11, 18 October 2024 (UTC)
References
- ↑ Google Developer Documentation Style Guide: "Language and grammar: Second person". Retrieved 27th April 2019.
- ↑ Microsoft Style Guide: "Grammar and parts of speech: Person". Retrieved 27th April 2019.
- ↑ TechnicalWriter Wiki: "Using the correct language". Retrieved 27th April 2019.
- ↑ Geoff Hart. Use of first, second, and third person in technical writing?, Technical Writing lists, August 17, 2005. Retrieved on January 1st, 2015