Gentoo Wiki talk:Guidelines

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)

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

Third person and passive voice are preferred, "you" is discouraged
Can you explain why? I've read the citation, but it seems to recommend the exact opposite. The gist of the citation, as I understand it, is that second person is standard practice, third person is less effective, and passive voice is often inappropriate. The reason I'm asking as that there've been some edits recently that go great lengths to replace "you" with strange and cumbersome formulas. For example, in the "Custom Initramfs" article (which inherently is a guide that tells you what you have to do yourself to get things going on your machine), the sentence "So everything you need, everything you want, you have to include it in your initramfs" turned into "Everything that is needed, everything that could be wanted, must be included in the initramfs." and this change leaves me utterly flabbergasted, at a complete loss of words. The only reason I haven't undone this edit is that I don't do edit wars on principle, and I'd lose anyway as I'm not the one who decides things around here. Can you show me one other popular Linux wiki that discourages the use of "you" because I can't remember seeing one; there is lots of "you" in the ArchLinux wiki for example, as in the Ubuntu Community wiki. And I just don't think they are doing it wrong... Frostschutz (talk) 18:23, 8 March 2015 (UTC)


 * The selection between second and third person writing, or passive voice writing, is indeed something that a wiki needs to decide on itself. The first article is mainly a resource for telling not to use first person writing. Most of the technical writing I do (outside Gentoo) uses passive voice (manuals and guidelines mostly). Also, the publisher I have some experience with (Packt Publishing) also prefers that its resources are written in third person.


 * As for the example, I think wikipedia('s manual of style) can be seen as the most authorative source on wiki-writing. Of course, I can cite a number of resources but those are biased (as I would then just search for "technical writing third person" and find a number of resources). Hence I think that wikipedia's style is a good source to base upon.


 * I do agree that blindly transcribing from an active, first person voice to a third person (or even truly passive voice) can become very awkward, and such sentences should then be updated or even rewritten. Often, this is an iterative approach so I really encourage you (and everyone else) to help us write beautiful articles while retaining a common style so that our wiki becomes a true source of wisdom ;-)


 * Hopefully this brings over my approach to this. I'll probably add the wikipedia source to the reference list as well.


 * --SwifT (talk) 19:45, 9 March 2015 (UTC)


 * Thanks for your SwifT reply. ;-)


 * I completely agree with the Wikipedia manual of style - but that's because it's an encyclopedia. It doesn't have anything to do with being a wiki. Articles in the Wikipedia never tell you what to do, they just describe things. Gentoo Wiki articles rarely describe things, they always tell you what to do to make stuff work. And the way I see it, without "you" that'll always be awkward, so it's not just a transcribing issue. Awkwardness aside, it also makes sentences much harder to understand (for me anyway), and much much harder to write.


 * Gentoo Wiki articles also aren't scientific papers that describe how a particular experiment worked, which seems to be what the other resources you linked are based on. Same with the Wikipedia style, I think I completely agree with those resources; I just don't think the shoe fits here.


 * Frostschutz (talk) 20:55, 9 March 2015 (UTC)


 * Thank you for your feedback.


 * I don't fully agree that the Gentoo wiki is completely different from a Wikipedia setup. You are correct though that it is not (only) information dissemination but also user guides, which is not found on Wikipedia.


 * For me personally, third person voice is easiest (like I said, it is something I've been asked to use by companies while doing technical writing work on their manuals, or by Packt Publishing for their resources), but I don't want to force this to others, so let's hear if there are others who would prefer to have (or support) second person as well. I can live with a mixture of second and third person voice if that is generally the preferred guideline.


 * --SwifT (talk) 13:43, 10 March 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/First Steps, 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)

Formatting info
I'm noticing quite a few edits that do little more than changing  to USE to USE to USE and back. Or gpg to  to gpg, etc. Lack of some guidelines on this matter will keep on resulting in somewhat useless edits. These edits do not do anything on the content (although some of them make the article harder to read instead of easier) and result in lots of notifications about modified articles.

Users who are trying to keep the quality of the articles up to par use watchlists, but such edits are cluttering the watchlists unnecessarily. It might frighten some contributors to properly watch over articles.

Translators also need to continuously update their articles with little benefit - do they need to follow the same formatting changes or not? This keeps their workload away from the more important stuff, such as translating remainders of articles.

I've created an updated Gentoo Wiki:Guidelines which attempts to cover formatting as well as some of the options mentioned above. I'd like to use this one as the "official" guideline (or at least try to cover similar information and detail), but if not it at least will be used by myself to streamline my own edits. --SwifT (talk) 17:04, 31 December 2014 (UTC)


 * I am going to update the Guidelines document with Gentoo Wiki:Guidelines on or after March 10th if there are no objections. --SwifT (talk) 17:05, 3 March 2015 (UTC)
 * Didn't notice this discussion until your edit to the page. IMO, much of the formatting in the "In-line layout elements section should be handled by templates. This allows site-wide standardization to a much greater degree than a mere guideline (makes it much easier for editors to notice and remember how different things should be formatted, and allows instant [caches notwithstanding] site-wide changes, if any formatting choices are changed). It also allows more complicated formatting of the items, including linking to sources of further information, possible tool-tip style explanations, etc., as desired. - dcljr (talk) 23:44, 10 March 2015 (UTC)
 * To be more specific, I guess my main objection here is to encouraging the use of for anything except inline snippets of code. I suppose one could argue that all of the currently suggested uses (including variable names, variable values, and command arguments/options) are technically snippets of code, but then why wouldn't command names be interpreted that way, as well? In any case, the replacement templates I'm suggesting be created (e.g., var, arg, opt, or whatever) would (initially, at least) simply use tags to accomplish their tasks, but they could do more, as I alluded to in my previous comment. As for , that tag is problematic, since its "literal meaning" (typewriter type) is so general (or simply not relevant to this wiki, depending on your perspective) that it doesn't clearly stand for anything in particular. Again, more specific templates could be created that use  , but its use would be "hidden" behind the more meaningful template names (e.g., command, term, linux-term, whatever). And, incidentally, we could also create code (moving the current code template to codebox) and kbd, just for editors who have trouble remembering that these cases are handled by the corresponding HTML tags. [g] Finally, note that I've already created keyword, which I have just changed to use  , in line with these new guidelines. - dcljr (talk) 02:11, 11 March 2015 (UTC)