Gentoo Wiki talk:Guidelines/Archive 1
After being marked as complete, the following discussions have been moved from the Gentoo_Wiki_talk:Guidelines article.
Discussions generally occurring between July 2012 to August 2015.
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)
- Works for me. No objections since July 2, 2012. Let's call this done. --Maffblaster (talk) 18:38, 11 April 2016 (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:
- When enabling translations on the pages, without a blank line the chapter title and the text would be seen as a single block
- In my experience with technical writing, having the titles clearly separated from the text makes it easier to (re)view
- 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
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)
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)
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)
Recommended Keyword: ~amd64 or ~arch
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)
Section Formatting overlaps with Help:Formatting
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
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)
- The
- 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)
- 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
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)
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.
- 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.
- I thought I'd finally weigh in on this topic of discussion. I agree with SwifT, generally speaking technical writing manuals (I can site sources if needed) instruct technical writers to explicitly use third person when writing documentation. The powers that be have defined this as the proper technical standard. Personally I believe third person is best suited for this the Wiki, since Gentoo is (currently) one of the more technical distributions available, and most of the articles on the Wiki are explicitly technical in nature. Also, with any technical writing, it is important to be as precise as possible without being overly lengthy.
- Sometimes when second person pronouns ("you" and "your") are used they are not precise enough, or are not technically true in context of what is being written. For example, the statement "Update your bootloader" is not as precise as "Update the system's bootloader" even though the second sentence is only one word longer. The difference being the bootloader might not belong to you in the sense of possession. Maybe it belongs to the company you work for. Looking at it another way, you, technically speaking, to not have a bootloader, but computer systems do. That might not be the best example of why technical writing needs to be precise, but I believe it is one reason why technical writing instructs writers to not use second person pronouns.
- It might be a bit inconvenient to convert all the articles to third person, but I believe it will be well worth it in the end for precise and excellent documentation. That's what we're striving for, right? And, hey, I have been making major progress recently! I hope this input is viewed as helpful. :) --Maffblaster (talk) 18:50, 27 March 2015 (UTC)
- An example of technical documentation is the Golang function reference or the Golang language specification. Those have a distinct lack of "you" because it's purely technical documentation of a package, its functions and return values, or of the language itself. I agree it would be wrong to use "you" there because it would be, as you say, less precise. I don't think we have documentation like this in the Wiki.
- Compare it with every other official Golang documentation (Effective Go, Golang FAQ, Golang Wiki, ...). Suddenly there's "you" all over the place. It's not technical documentation in the strictest, objective sense, but rather it's documentation that's meant to teach you something. Replacing "you" with an arbitrary user or programmer (even though it clearly means *you*), would turn a perfectly natural language into something cumbersome and thus less precise. It's not progress, it's backwards. I think this is much closer to what we have in the Wiki.
- Frostschutz (talk) 15:27, 28 March 2015 (UTC)
- Minor grammatical quibble: Even in an imperative such as "Update the system's bootloader", there is an implicit "You" at the beginning. [grin] To truly avoid second-person,
you would— er, I mean… passive voice would have to be used. Trying to completely avoid second-person in articles will inevitably result in very awkward sentence constructions — especially considering that most articles here (I assume) contain at least some instructions that the reader can follow to accomplish something. As for the Wikipedia analogy, while some of our articles might be somewhat encyclopedic in nature, the type of documentation I just alluded to has more in common with texts at Wikibooks, and their Manual of Style doesn't mention active/passive voice or first/second/third person at all. My recommendation, therefore, would be a hybrid approach: encourage the kind of "technical" or "encyclopedic" style that has been mentioned here when presenting purely factual information, but allow the use of second person (either implicitly or explicitly) in instructional content (i.e., "do this to accomplish this task"), especially if it results in more natural, understandable prose. (After all, part of having clear, correct documentation is making it obvious when the user is being asked to actually do something.) - dcljr (talk) 04:22, 29 March 2015 (UTC)
- Minor grammatical quibble: Even in an imperative such as "Update the system's bootloader", there is an implicit "You" at the beginning. [grin] To truly avoid second-person,
Formatting info
I'm noticing quite a few edits that do little more than changing USE to USE to USE to USE and back. Or gpg to gpg 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 <code> 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 <code> tags to accomplish their tasks, but they could do more, as I alluded to in my previous comment. As for <tt>, 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 <tt>, 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 Template: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 <tt>, in line with these new guidelines. - dcljr (talk) 02:11, 11 March 2015 (UTC)
- I agree with Dcljr. If/when the look and feel of the Wiki needs to be updated, using templates for in-line formatting in the articles will provide flexibility where in-line HTML tags will not. I also like the idea that tool-tip style hints to more information could be provided with templates, where the same is not possible using HTML tags. I'm not saying that all templates should have hints, but I like having the option available.
- I've been seeing the need for additional templates while recently editing a few different articles. The {{Path}} template is currently the best suited template for instructing the reader through GUI "paths" (clicking buttons, check boxes, menu items, etc.), and I've been using as such, but I think that was a poor choice on my part. The {{Path}} template and the <tt> tag do not provide enough differentiation for in-line instructions in certain cases. This is especially true when addressing filesystem paths, terminal commands, and GUI menu "Paths" all in the same paragraph. I believe comes back to making style changes easily possible using a full template system for all of the styles. I suggest doing this for any formatting/style items that may need to be sightly tweaked for readability's sake in the future. Some of these formatting/style issues can be viewed on the PPC FAQ article and the main FAQ article.
- As Dcljr stated, I suggest being more specific with each item listed in the in-line layout elements. This would mean providing a few new templates ({{Var}}, {{Arg}}, {{Opt}}, {{GuiPath}}) and then updating the existing articles accordingly. I would have no problem updating all the articles to these standards. After the articles are updated style/formatting tweaks could be made as needed to all the articles at once. --Maffblaster (talk) 20:01, 27 March 2015 (UTC)
- Personally, I'm fine with more semantic meanings to tags. But be aware that this is one of the reasons why GuideXML (the predecessor of Gentoo's documentation) did not get much attention, as asking contributors to know semantics is creating a higher learning curve.
That being said, the disadvantage of XML (which is forcing stuff to users), the wiki could allow contributors to relatively ignore these semantic taggings and rely on the editors of the wiki to update the guides accordingly. So I'm in favor (but don't ask me to create the templates, I rather let that be done by people who know mediawiki stuff better ;-). --SwifT (talk) 08:58, 28 March 2015 (UTC)
- Personally, I'm fine with more semantic meanings to tags. But be aware that this is one of the reasons why GuideXML (the predecessor of Gentoo's documentation) did not get much attention, as asking contributors to know semantics is creating a higher learning curve.