Talk:Style Guide

Feedback

First of all: This seems to be a pretty good start! Now the actual feedback:

• In Style guide#Expired terminology, you mention that we should use "Residents" instead of "users", "subscribers", "customers", "avatars", etc.. I would like to strike "avatars" in this context. While "Resident", "user", "subscriber" and "customer" might be used synonymously, an avatar is something completly different and shouldn't be confused with the others (not even in this style guide). The use of the term "avatar" in a KB article should be allowed where appropriate - at the point where we're referring to one physical representation of a Resident inworld. For example at an article like "How can I change my appearance?" or something similar.
• The style guide as such should be named as what it is (like "Style guide for Knowledge Base articles") and moved to either the Help: or the Project: namespace. It also might be tagged with {{Help|Wiki=*}}.
• The guide gives advice to set links where appropriate. Once the KB is moved to the wiki, we'll basically have two help resources. The KB and the Help Portal. This isn't ideal. The question is: should these be distinguished or merged? I'd like to go with "merged". In case the answer is "ditinguished", then we'll need a guideline when links from one resource to another are allowed and how to mark them (in case they need to be marked). For example, you're giving the advice to link to glossary items, which are part of the Help Portal / not "verified". I can see that there will be quite some work to verify that the Help Portal articles are up-to-date and accurate, though over time, it might become quite hard to keep them distinguished anyway. So merging them from the start seems to be a good way to go.
• I'm not sure why you mention that the use of Template:KeyCombo should be refused. Is it because the viewer uses minus signs instead of plus signs? You can also use Template:Keypress for single keys or make a specific Template:KeyComboKB which uses minus signs instead of plus signs and which becomes redirected to Template:KeyCombo once the dispute is settled?
• I'd recommend to use {{L$}} (which results in L$) instead of L$ (nice hovertext).

err... I think there was more that I wanted to mention though it's quite late and I'm pretty tired. Maybe I'll remember more tomorrow. Nite and thx for the guide! :-)
-- Lynch ^{(talk|contribs)} 00:40, 12 June 2009 (UTC)

Response!

Zai! THANKS for your sharp insights as always.

Quick version: all great ideas, some of them may not be done yet but should be considered.

Details:

• Yes, we absolutely do consider that "avatars" should be used whenever appropriate. We'll clarify that soon after I chat with my team (just wanted to reply to you quickly).

• Also agree that's a better place to move this page!

• Merging the two resources is a possible future if the KB2Wiki Pilot succeeds. It's one of those "We can see it happening, but other stuff needs to happen first" — in any case, important to prepare for that possibility now.

• Template:KeyCombo is not refused, but is another one of those "likely later, but not yet" things because we don't have an easy way to automate all the conversions from their KB source pages. (And might have to end up changing them one-by-one.) Any ideas here?

• Also agree about using Wiki-specific features which make it easier to glossary stuff — L$ is a great example and we'll be making more allowance for that. I bet there'll be lots of opportunities to spot many tweaks.

- Torley on 2009-06-13 @ 6:25 AM PST

OK, will try to be patient and cross fingers that the move will succeed :-)

-- Lynch ^{(talk|contribs)} 14:02, 13 June 2009 (UTC)

Oh, @changing Template:KeyCombo one by one: I think it would be a similar search & replace algorithm like the one you're using to replace the HTML syntax with wiki syntax. Once the algorithm finds something like CTRL-ALT-SHIFT-H, it should replace it with {{KeyCombo|ctrl=*|alt=*|shift=*|H}}. though I can't tell how to implement it exactly, since I don't know what you're using there. But changing it by hand wouldn't take so long either... We need to check each new article for proper conversion anyway.

-- Lynch ^{(talk|contribs)} 14:15, 13 June 2009 (UTC)

In the context of the LSL Portal, we have stricken the term Agent. While the distinction between Avatar and Agent is important, it confuses people none the less and is a categorization nightmare. The best part about this, I don't think anyone has noticed. -- Strife ^{(talk|contribs)} 17:55, 13 June 2009 (UTC)

If the KB and Help Portal are to be merged, instead of branding content as unofficial, why not certify content as official? Put a special badge on the article. You said there were things that needed to happen first, could you elaborate on what they are? -- Strife ^{(talk|contribs)} 18:01, 13 June 2009 (UTC)

More feedback

Overall looks like a sensible set of rules. But me, too, got some comments about the details:

• Although the style guide itself isn't an article moved from the KB to the wiki, isn't it a document formal enough that it should adhere to the very rules stated in it? E.g. the link labeling rules are violated by the link at the end of the "Trademarks" section.
  • (Tip for printing articles violating this rule: Click "Printable version". Looks ugly but you'll see all the link URLs should you need them later.)

• "Nobody likes the passive voice. Don't use it. "
  • Not true! I like it, when it isn't used in a clumsy way. (<-- See? It's possible!) I agree it shouldn't be overused, though. If in doubt, use active voice.

• @Style guide#Terminology:
  • Pie Menu: working around this term by using "right-click on ..." might not work when talking to Mac users (at least those using a true one-button mouse). Is there some term for the (semantic) action of bringing up the context menu at the mouse position, independent of how it is done (be it right click or Control-click or any other means ... I once talked to a new resident using a PC mouse but backside front, with the cable pointing towards her ...)? "Context click" would be a logical term, but I don't think many would know what it means.
  • Dialogs: In computing this term stands for "[a] window that prompts the user to enter information" (from wiktionary). In today's usage of the word, the input can be as few as pressing an OK button, even if that's the only button available. But some interaction with the user should be there, so while the llDialogs, the Group Notices, and pretty much everything blue in the top right corner would actually be dialogs, the friend-status notifications and other toaster pop-ups in the bottom right corner aren't.
• @Style guide#Expired_terminology:
  • "Residents" instead of "users", "subscribers", "customers", "avatars", etc.: Aren't these describing different concepts? ("Avatars" is mentioned by Zai already.) I'd say that ESC, being a commercial licensee of the viewer sources, is a customer, too. But (although it's employees might be), the company isn't a Resident. I take "Resident" to mean a member of the Second Life community (i.e. a user of the service known as LL's Agni#Agni grid). Users of LL's clients might connect to other grids, so aren't necessarily Residents. Because the KB isn't only about the service, but also the client software, these users might consult the KB, too.
  • Talking of clients (as in "client software", not customers), we might have to add "Viewer" to the expired terminology list somewhen in the near future, except when part of "Second Life Viewer". See Melinda's post to SLDev. (Of course it's possible that this will never become official policy, so we shouldn't change it before we know more.)
• @Style guide#What_to_capitalize
  • Second Life Region names: Shouldn't those be capitalized just as seen on the Map? (Maybe all Region names are capitalized anyway, I don't know.)
  • The first letter of each term that identifies a particular button or menu item within the Second Life client: Same here, shouldn't the capitalization follow the actual labeling as seen in the client?
  • Acronyms: What about acronyms that aren't just based on initial letters ("Sim", "HiFi") or such that already have an established way of what letters are capitalized (like the German "GmbH" or your own brand "inSL")?

• "First Life": This can't always be worked around by "outside of Second Life". WoW and Tolkien's Middle-earth aren't part of Second Life, but you wouldn't want to include them when writing e.g. "Concerning copyright, remember that real life laws also cover content in Second Life." So the question should be whether "real life" or "First Life" is the preferred term for use in the KB.

-Boroondas Gupte 22:57, 13 June 2009 (UTC)

Another response!

I really appreciate you thinking about these points in-depth, Boroondas. I'll check with the Migration Team to give more details — and yes, in a number of cases, these are strong guidelines but not absolutes. Exceptions can be made as-appropriate.

Also, the Knowledge Base only applies to Linden Lab-supported products & services; there are other pages about OpenSim and beyond, but we won't document or support those. (The respective gurus building those resources up are more than welcome to take the guide as inspiration, however.) There is bound to be more beneficial stuff that is done "at your own risk", such as stuff in the Advanced menu and experimental features. - Torley on 2009-06-15 @ 2:19 PM PST

Template:KeyCombo

Torley said: "Template:KeyCombo is not refused, but is another one of those "likely later, but not yet" things because we don't have an easy way to automate all the conversions from their KB source pages. (And might have to end up changing them one-by-one.) Any ideas here? "

An automatic conversion sounds like a task for someone with awk or sed skills. However, I think it would also be acceptable to do a manual conversion, even if both styles will be around during the transition. In my opinion, to retain the professional appearance, the following should be sufficiant:

• It should only be this two styles; don't invent any new ones.
• Don't mix the two styles in the same article. Convert an article as a whole or not at all.
  • As KB articles don't tend to be too long, this should be doable.

Also, the style guide should state which one is preferred for new articles.

--Boroondas Gupte 15:07, 13 June 2009 (UTC)

Response!

I agree about consistency per-article: if someone does an editing pass through an article, all keystrokes should be converted.

I've also shared your suggestions. - Torley on 2009-06-15 @ 2:21 PM PST

First Life

I always liked the term " meatspace". It's even in the Oxford English Dictionary... but so is xenology -- Strife ^{(talk|contribs)} 21:22, 14 June 2009 (UTC)

lol, didn't knew that one (^_^) great! I'll add it to my treasury of words. TY -- Lynch ^{(talk|contribs)} 21:46, 14 June 2009 (UTC)

Cyberpunk!

I know "meatspace" from cyberpunk. Such is the struggle with words, though: until they gain common currency, they may hold a great meaning to a smaller audience but be lost on the masses. (Remember when we called cars "horseless carriages"?) So, how we "first life" may very well change in time. I always adore the forward-thinking, however. - Torley on 2009-06-15 @ 2:25 PM PST

Real Life

People had resorted to use "real life" or "RL" to avoid confusion between statement on which life you have if a user has more than one Second Life Accounts. Surprising no matter how hard people stressed out the "alternative" accounts in term. It's long overdue for Linden Lab to rename First Life to Real Life in profile. It's required to change for the stake of non-Second Life users in courtroom. --Vincent Nacon 12:42, 16 May 2010 (UTC)

"Expired" terminology and acronyms

Just a few thoughts. Instead of expired wouldn't depreciated be the more accurate and more clear term to use since words don't expire as such? Also, should some of the information from Acronyms be imported over to either a sub-section of terminology or it's own section since that could be relevent too. I also think that there needs to be clear guidelines for the use of acronyms in KB articles since they may be confusing to those who don't know what the acronym means (say new users who need help on an issue) or can be a valuable tool. GW ^(T|C) -- 22:02, 14 June 2009 (UTC)

Deprecated?

I believe it's "deprecated". But yes, that would be welcome clarity. As mentioned above, I'm gonna meet with the team and we'll revise the Style Guide.

I think it helps to hyperlink/hovertext acronyms to an expanded definition whenever possible. This is another area where, if the KB2Wiki Pilot succeeds and we move the WHOLE KB to the Wiki, we can easier consolidate resources and remove unnecessary duplication. - Torley on 2009-06-15 @ 2:27 PM PST

And yet I can still spell antidisestablishmentarianism correctly without a spell checker, go figure :) GW ^(T|C) -- 21:47, 15 June 2009 (UTC)

I did the replace on that term, not sure about how to best go about the acronyms. On wikipedia there was actually a monobook.js script that people could use that would create a javascript hover bubble with a previous of the page and various options so it is possible although how to do that is more Zai Lynch's territory and it would have to be used on the global file so everyone could use it. GW ^(T|C) -- 22:01, 15 June 2009 (UTC)

Hyphenation

I think we could use a clear policy on hyphenation in both sections and section titles. As can be seen in Avatar Movement: How do I walk or run? Consistency is good but can be weird. GW ^(T|C) -- 21:46, 25 June 2009 (UTC)

History Notice

The edit history of this file couldn't be preserved. For the previous history, please look at the old backup. It is located at Project:Flagged Revs Backup/Style Guide. --Khepri Contractor 02:16, 21 July 2010 (UTC)

It should be possible to merge the old and new history of the page. See MediaWiki Administrator Handbook on "Edit History" and Wikipedia's How to fix cut-and-paste moves > Repair process (for admins). Whether it's worth the hassle (and risks), I cannot tell.

--Boroondas Gupte 10:52, 21 July 2010 (UTC)

Following this procedure would re-introduce the problem which lead to the move in first place.

The problem was, that the Special:OldReviewedPages list contained items that could not be removed. This is caused by pages that were once treated with flagged revisions, but were then exempt from the flagged revs treatment again. They remained as artifacts any time a new edit took place at such a page (although it could not be reviewed).

After much testing, I figured out that the only way to get rid of these artifacts was, to export, delete and re-import the pages. The xml created by the export doesn't contain the flagged revs information, therefor it was fixed after the import.

However, exporting the pages with all the revision history lead to too huge xml files. They couldn't be imported again (via the web-interface). The old bug triage page for example already exceeds 2MB.

So what I did was, I moved the pages to a namespace that in itself isn't affected by flagged revisions. The current flagged revisions configuration is set in a way that it only affects pages in the main namespace and in the template namespace. That's why I moved them to "Project". Once they were moved to project, they were removed from the Special:OldReviewedPages list. Then I deleted the redirects in the main namespace and imported the last revision of the articles again. That's what lead to the current setup.

Moving the page from the project namespace back to the main namespace will re-introduce the initial problem of the cluttered Special:OldReviewedPages list.

I think the current resolution is acceptable, since all information is preserved, even though the Project:Contribution Agreement allows LL to ditch the history. I just personally felt that this would be wrong, as long as there's a work-around.

--Khepri Contractor 12:04, 21 July 2010 (UTC)

I see. To me, the inability to cleanly exempt a page from flagging sounds like a bug in the extension. I like having the history around for informational purposes, so thanks for preserving it elsewhere.

--Boroondas Gupte 13:42, 21 July 2010 (UTC)

Yeah, I agree on the bug-interpretation. It's annoying...

Welcome! --Khepri Contractor 17:16, 21 July 2010 (UTC)