Gentoo Wiki talk:Guidelines/Archive 1

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

Section Formatting overlaps with Help:Formatting
The sections Gentoo_Wiki:Guidelines and Gentoo_Wiki:Guidelines are widely overlapping with Help:Formatting, Help:Formatting and Help:Formatting. 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)

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


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

US English as language?
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)

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

Sentence case in page titles
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)

Recommended Keyword: or
Putting in architecture unspecific articles could be misleading for users of other arches. Wouldn't it be better to recommend putting 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)

Guidelines Guideline
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)