Gentoo Wiki talk:Guidelines/Archive 1

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

Guidelines Guideline

Talk status

This discussion is done.

I would like to suggest that ideas get vetted here before they are moved to Gentoo Wiki:Guidelines. /Ni1s 16:51, 13 March 2012 (UTC)

Categorization

Talk status

This discussion is done as of Jul 2 2012.

After discussion on IRC, I propose we do not add articles to the parent categories, when they are categorized for their subcategories. — yngwin 11:35, 2 July 2012 (UTC)

Works for me. No objections since July 2, 2012. Let's call this done. --Maffblaster (talk) 18:38, 11 April 2016 (UTC)

Creating blocks

Talk status

This discussion is done as of Aug 17 2014.

I'd like to discuss a change to the guidelines, namely to allow a blank line after a title (right now it says that there shouldn't be any).

I recommend this for the following reasons:

1. When enabling translations on the pages, without a blank line the chapter title and the text would be seen as a single block
2. In my experience with technical writing, having the titles clearly separated from the text makes it easier to (re)view
3. By aggregating the title with a paragraph, an editor would suggest that these two need to be seen as a single entity, which isn't the case. A title is used for the entire set of paragraphs (and other entries) until the next title.

For readers, this doesn't matter (no difference in how the page is displayed). — The preceding unsigned comment was added by SwifT (talk • contribs) 13 April 2014

I agree. FWIW. - dcljr (talk) 03:32, 17 August 2014 (UTC)

US English as language?

Talk status

This discussion is done as of Dec 6 2014.

I think we need to request contributors to use one "English", of which I suggest to use US English (American English).

Both are fine for me, but my experience with writing documentation (and technical editing) seems to suggest that American English is more popular to be used (for instance, publishers of IT technical books often request it to be in American English).

--SwifT (talk) 18:34, 28 April 2014 (UTC)

Probably makes sense to encourage (but not necessarily require) American English, since most other Gentoo-related documentation is already in that variant. (Full disclosure: I am American.) Is there anything in particular that raised this issue in your mind? - dcljr (talk) 03:30, 17 August 2014 (UTC)

The topic came forth when I noticed someone modified a page that I was watching just to switch to British English, which was imo not that useful and could trigger retranslation events (unless the translation approval tells that all changes do not need translation). --SwifT (talk) 11:01, 6 December 2014 (UTC)

Sentence case in page titles

Talk status

This discussion is done as of Dec 6 2014.

As I have always done on every wiki I've been (or potentially was going to be) active on, I strongly suggest encouraging sentence case in page titles as much as possible, to make it easier to link to other articles in running text (as I just did to a Wikipedia article [technically, a redirect] in this sentence). I see that this seems to already be the convention in much of our featured documentation, but there are several subpages, like MySQL/Guide, that use title case instead; this may be OK (apart from consistency issues) since you'd have to "pipe" that link to use it in prose text anyway—but I still don't like it.[g] Fortunately, very few of our "top-level" (i.e., not a subpage of another article, so title not containing a /slash) featured pages use title case (one example is Mailfiltering Gateway). See the many examples at the aforementioned Wikipedia article for an indication (however contrived) of how much of a nightmare guessing the right capitalization can be if you don't pick a simple, standard guideline and stick with it. (Technically, I'm suggesting that each page title itself be in "sentence case" but links to it in running text be in what they call "mid-sentence case" — which is made possible by the first character of a link being case-insensitive.) - dcljr (talk) 04:12, 17 August 2014 (UTC)

OBTW: sentence case is already relatively established in our page titles, but section headings are a completely different matter. See, for example, the section headings in Gentoo installation tips and tricks, which use a mixture of sentence and title case. I recommend sentence case here, too. - dcljr (talk) 04:19, 17 August 2014 (UTC)

I agree with using sentence case for titles (both page and section). --SwifT (talk) 11:05, 6 December 2014 (UTC)

Links

Talk status

This discussion is done as of Mar 13 2012.

See Also? External Links? Further Reading? or just plain Links? And what about related material? /Ni1s 16:48, 13 March 2012 (UTC)

I propose External resources, as I've started using on the Zsh page. — yngwin 14:26, 19 June 2012 (UTC)

Let's change that to See also for *.gentoo.org links, and External resources for others. Comments? — yngwin 11:35, 2 July 2012 (UTC)

I agree with the See also and External resources approach. --SwifT (talk) 10:58, 6 December 2014 (UTC)

The guideline was updated already with this, so closing the discussion. --SwifT (talk) 17:05, 31 December 2014 (UTC)

Recommended Keyword: ~amd64 or ~arch

Talk status

This discussion is done as of May 13 2012.

Putting {{Key|~amd64}} in architecture unspecific articles could be misleading for users of other arches. Wouldn't it be better to recommend putting {{Key|~arch}} for those general cases? --Charles17 (talk) 06:21, 8 May 2015 (UTC)

That's a fair point. I'll update the syntax there, but leave ~amd64 for the example paragraph. --Maffblaster (talk) 06:38, 8 May 2015 (UTC)

Be careful not to confuse {Key} and {Keyword}. - dcljr (talk) 09:26, 9 May 2015 (UTC)

Section Formatting overlaps with Help:Formatting

Talk status

This discussion is done as of June 05 2015.

The sections Gentoo_Wiki:Guidelines#In-line_layout_elements and Gentoo_Wiki:Guidelines#Use_of_newlines are widely overlapping with Help:Formatting#Text_formatting_markup, Help:Formatting#Paragraphs and Help:Formatting#HTML_tags. This is confusing for both readers and editors. IMHO there should be one single source with these information. By transclusion the source content could then be included in the page, but a link leading there should be sufficient. --Charles17 (talk) 06:19, 14 May 2015 (UTC)

I think we should indeed watch over unnecessary duplication. Having multiple authorative sources doesn't help, especially if they are not in sync. The namespaces do imply some difference in how they should be read or interpreted though. The Help namespace is perhaps interpreted by people to be general for mediawiki, whereas the Gentoo_Wiki namespace is about this wiki.

With the guideline page, we want to inform contributors what the specifics are on developing documentation and contributing to the wiki.

But I would definitely not mind updating the Help:Formatting page for this and link to it from the guidelines page.

--SwifT (talk) 07:30, 18 May 2015 (UTC)

I have updated the Help:Formatting article with a tip pointing people to this location for Gentoo-specifics on formatting articles. Feel free to change the wording if you think it needs more clarity. --Maffblaster (talk) 18:10, 5 June 2015 (UTC)

<tt> tag is not supported by HTML5

Talk status

This discussion is done.

According to w3schools.com the <tt> tag, which we are currently using in the Wiki Guidelines, has been depreciated and is not supported in HTML5 (although browsers will still provide support). If we want to move away from that tag we have a lot of editing to do. Since the text being marked up by the <tt> tag will still render in browsers properly, it is not really a big deal, however this is some evidence that supports the case I was building in the past for using templates for all markup performed inside the Wiki articles. ;)

That aside, I suggest we change the Guidelines to include the {{c}} template in place of the <tt> tag for commands or GNU/Unix concepts. If interested take a look at the {{c}} template before commenting.

Just for reference, the following is a list of in-line markup tags that are available in HTML5:

• em: Renders as emphasized text
• strong: Defines important text.
• var: Defines a variable.
• code: Defines a piece of computer code.
• kbd: Defines keyboard input.
• samp: Defines sample output from a computer program.

Thoughts? --Maffblaster (talk) 22:54, 6 August 2015 (UTC)

The <samp> tag shows the output we would need for most of our <tt> usage. I still find the <kbd> to be too hard in the contrast it has in the document. It detracts from the content if it is used many times.

If I look at the Template:C page I see no information? All I can do is try it out to see how it looks.

I'm okay with using a {{c}} tag to replace the <tt> ones.

--SwifT (talk) 08:31, 7 August 2015 (UTC)

I took the liberty of adding the element names to the list in Maffblaster's comment, to make discussing it easier. To address the actual point: I would have a problem with using any of these elements (except 'em' and 'strong') purely for their visual appearance. The last four elements have actual meanings which we should stick to if we use them (even if only inside of templates). If we don't like the look of any of these HTML elements, that can be changed in the site-wide style sheet. (Also, can we not move this section to the bottom, so the page remains in chronological order?) - dcljr (talk) 09:58, 7 August 2015 (UTC)

[Just noticed this page already wasn't in chronological order, whether you think that should be "forward" or "reverse". Which convention are we trying to stick to here? - dcljr (talk) 10:06, 7 August 2015 (UTC)]

dcljr, I moved the closed discussions to the archive sub-article and left the remaining few open discussions. I wasn't thinking about the open discussion's order of appearance at the time. Since the <tt> tag as been partially dealt with I'm marking this discussion as closed. --Maffblaster (talk) 23:33, 11 August 2015 (UTC)

Use <var> tags for variable names

Talk status

This discussion is done as of August 26, 2015.

I hate to purpose a change this late in the but, but I think <var> tags for be better for variable names whenever they are referenced in in-paragraph text. We should definitely continue using <code> tags for variable values. The <var> tags function is to be used as I propose here, so it seems we should use it 'as intended' in our formatting here on the Wiki.

For example: Set the USE variable to python.

I'm okay with that. Too bad HTML doesn't declare a <val> ;-) --SwifT (talk) 18:29, 27 August 2015 (UTC)

I added it to the Guidelines list of formatting stuff. Should be good to go! I'll leave this discussion on here for at least a week just in case someone else would like to comment. Sometime after that I will send it off to the archive. --Maffblaster (talk) 07:34, 28 August 2015 (UTC)