User talk:SwifT/Styleguide

Can you please clarify the use of <ref> and {{reflist}} when citing sources? I have seen them used in some articles on the Gentoo Wiki and I have used them in the Sony DualShock wiki. Should they be used and if so where should they be placed ("External resources or "References")? --BT (talk) 00:45, 1 January 2015 (UTC)

Good idea. I tried to make a reasoning for using them and how/when to use them. I see References personally as a different section (alongside External resources and See also) whose sole purpose is to provide links to proof-related material (i.e. a claim was made inside the article, or some method has been borrowed by another resource) which the end user usually does not want or need to visit but is meant as a way to provide a source of a claim.

I haven't used <ref> myself much (or perhaps even at all, can't remember) but I did notice its use on a couple of articles as well. --SwifT (talk) 10:03, 1 January 2015 (UTC)

Thank you. --BT (talk) 10:37, 1 January 2015 (UTC)

Typo in references usage example

The redundant </nowiki> close tag is in “Example use of a reference”. — Totktonada (talk)

Good catch! Updated. --SwifT (talk) 18:43, 5 January 2015 (UTC)

More about references

Maybe add note about {{reflist}} and its usage? Article source is contain good example, but explicit description will be better :) —Totktonada (talk) 14:25, 15 January 2015 (UTC)

And second question: how references to man pages must be formatted? —Totktonada (talk) 14:25, 15 January 2015 (UTC)

Answer youself: wrapping it into tag looks nicely.

I have added in where to put {{reflist}}.

Regarding manual pages, I would personally refer to the online manual page (if there is an authorative source) or just mention that it is the manual page. I seriously dislike the use of the <kbd> tag as it has a very high contrast and looks unprofessional if it is overused. --SwifT (talk) 15:59, 14 February 2015 (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)

BTW, the styleguide has been moved to the main styleguide (was set for today), but I also moved this discussion over to the talk page of the official guidelines. As the suggestion for third person was already present in the previous version, I did not want to wait with the "promotion" of the style to the official guidelines until this was resolved.

--SwifT (talk) 14:00, 10 March 2015 (UTC)