Help talk:Editing

From Valve Developer Community
Revision as of 16:12, 23 September 2007 by Andreasen (talk | contribs) (Moved the code tag discussion here.)

Jump to: navigation, search

Is there any way to make new pages? I've got a bunch of tutorials and other stuff on Steam that could be with being added.

I think you just need to modify the url in your address bar to go where you'd like. If I wanted to start a page on "stuff", I'd use the address http://developer.valvesoftware.com/wiki/Stuff . No doubt there is an easier way, but there are some significant differences between the SDK wiki and other wikis like Wikipedia. User:Geogriffith
Clear and simple information on how to create new pages should be added here. This is one of the most common things that people have trouble with. --JeffLane 01:27, 1 Jul 2005 (PDT)

Does anyone know how to add pictures? True_Unity 08:26, 11 Dec 2005 (PST)]

<<You see that link over yonder that says Upload file? Push it—ts2do (Talk | @) 11:43, 11 Dec 2005 (PST)

Additions

Added bullet points. I noticed someone added something about redirects. 6-28-05 User:Geogriffith

Added some more info about math symbols, equation rendering. Looks like it's not enabled though because I can't get it to work, am I doing something wrong? -- MrAnderson 13:55, 4 Jul 2005 (PDT)


Code tags

(This discussion originated on the Talk:areaportal page, and was moved here.)

I am pleasantly surprised that you (Jeff) put so much effort into it with pictures and all. From being just a footnote mentioned as parts of several bloated articles, areaportals now have a beautiful "home". However, as uncomforting it is telling you this, the entity <code> format you used was scrapped years ago. (It looks ugly and distracting, and confusions over "light" entities has been unheard of.) Do you mind if I remove the code tags? --Andreasen 10:37, 20 Sep 2007 (PDT)

I mind. I think it has been established as part of this wiki style to code-tag entity names amongst others. --Tourorist 13:03, 20 Sep 2007 (PDT)
Uh, name five articles that still has the code tag (that isn't 1-2 years old). --Andreasen 13:45, 20 Sep 2007 (PDT)
There was some discussion of this last year, but it was not conclusive enough to merit changes as the reasons given were completely subjective and there was no consensus. The Help:Editing#Formatting_guidelines page reflects the closest guide to current usage, as well as a number of existing articles on the site that use the tags in this way. The age of the articles is also not very relevant. In fact, it's the opposite if most of them are using this format and there was no consensus on a change. In the case of this article, I actually got most of this formatting when I moved sections from the original Controlling Geometry Visibility and Compile Times page.
That said, I don't feel that strongly about this either way, so if a significant number of editors come to a consensus and want to change it in some way, that's fine. Though I do feel that entity names really need some visible marking to show that they are not just English nouns. They are keywords with significance and are almost always the focus of the text. It's the same reason we highlight other keywords like Menu Titles. Why would it be any different? There are precedents in technical documentation for this. Capitalization is often used for important keywords, but that would just be confusing in this case. Another other option is bolding, which might work better. Hope that helps. --JeffLane 18:52, 20 Sep 2007 (PDT)


I tried to find the previous discussion we had about this, but couldn't find it.
I rarely see code tags being used in articles, so I don't think that the Help:Editing page is reflecting the current usage. I've seen only three pages that uses the tag for entities as of late: Controlling Geometry Visibility and Compile Times, areaportal (this page), and the one that User:Tourorist "codified" himself, believing that the tag was current usage.
The reason for this is natural: Besides being an unnecessary eyesore to readers, "<code>[[entity]]</code>" also takes twice the amount of characters to write (including special characters) than "[[entity]]", and entities are used much more commonly than console commands and file paths are.
As for special marking, many articles doesn't focus on a particular entity, but of a topic involving many entities, where they themselves are often just mentioned as mere alternatives, or even exceptions (like "Prop_physics should not be used for this."), drawing attention to totally different topics. As it is now, when entities are first mentioned, they are linked to (according to current guidelines) which is marking them in blue, and the topic is then understood. If need be, we could mark them all in blue, every time they're mentioned. That should be the closest natural markup for authors, and just looking at this very text, that markup should make all the entity names stand out, without drawing too much attention to it.
I can't argue with technical documentation standard, but judging by the article you just wrote, turning a matter-of-factly (technical) article into something a little more greeting and fleshed out, I don't think that the VDC is a 100% technical manual. Also, if compared to wikipedia, I don't see any technical lingo being marked up there.
Entities are rarely even able to be confused with nouns. Of all the entities (I checked the lists.) only four doesn't have an underscore (_) in them: Cycler, gibshooter, infodecal, and light. There are two easy methods to deal with these:
  1. You can set the topic by linking to the entity article at its first mention (and if in any way unclear, later mentions as well), like above. The latter mentions of it is then obvious.
  2. You can refer to it as "the xxxx entity". The only entity that even comes close to being confused then, is the light entity, if someone would assume that the article was about weight instead of lighting, which would be virtually impossible to do, considering how different these topics are. When dealing with light entities as a category, one can refer to them as "light source entities" to avoid confusion.
I wish there was a significant number of authors around to vote for any change, but considering that most articles currently use the lighter "[[]]" markup, that change would be back to using code tags. It's easier to remove the guideline than to change most of the articles in the wiki. One can't seem to find entity code tags through the search engine, but could I, I would gladly hunt down the last remaining code tags myself, if only allowed, because it makes every mention of them a bother. --Andreasen 06:48, 21 Sep 2007 (PDT)
I wasn't the one who introduced this practice, if that's what you imply. And like Jeff, I am neither for nor against on this issue, my sole interest (as evident from my contributions) is in overall consistency of wiki, whichever way we go. --Tourorist 07:23, 21 Sep 2007 (PDT)
I'm not at all blaming you for following what you believed to be current standards. --Andreasen 08:34, 21 Sep 2007 (PDT)
The VDC documentation is technical writing, like any type of help files or user manuals are. Creating content with the Source Engine is a technical subject. It is from that perspective we try to evaluate these kinds of decisions.
I would agree with a change if it's a positive one, or even an equal one, but I'm not convinced that removing all the entity formatting is positive. They are an important keyword, essentially a cross between a menu command and a piece of code (depending on the context), and their exact name is significant. Text formatting of some type needs to reflect that distinction when no link is present.
The suggestion of standardizing formatting in blue is reasonable one, but would make them look like false page links, so it shouldn't be that, and adding color tags is prone to errors. Using bolding after the first link is a better alternative since it has simple wiki syntax. That would put them on the same level as menu titles and commands, which does make some sense from the perspective of most of our users. For them, picking entities is a menu choice in Hammer and the primary context they will see them (few of our users read the .fgd file, for example). Italics is another alternative, though they don't read particularly well in this typeface and point size, and readability is critical for entity names.
As an aside, I've never been too happy about the extra gray shading behind the text in the code tags. It too dark on some monitors and lighter on others and the monospace typeface that shows up with code tags is really sufficient for the purpose. I will likely remove it in the site-wide CSS, no matter what we decide with entities. --JeffLane 11:16, 21 Sep 2007 (PDT)
The gray background is now removed from code tags, and the space between section headings is now slightly increased (especially level 2 sections). --JeffLane 14:47, 21 Sep 2007 (PDT)
When you wrote that the format had precedents in technical documentation, I assumed the highlighting in gray was some sort of technical manual standard that I must have never seen before, but this page tells me it's pretty in the hands of the manual designer.
Why would linking to them look like false page links? All entity pages has been written, so unless they are spelled wrong, they'll definitely be blue - not red.
Although I prefer bolding over code tags, the users just see the entities in the plain, unformated text format and font, if that's what you mean. I've never seen entities as titles or commands - just plain names - but I can't speak that much for other users. I really wish more people would take part in this discussion.
I don't see any changes in the CSS. I've tried updating the page. Perhaps I will have to delete the browser cache for the changes to take effect. --Andreasen 16:16, 21 Sep 2007 (PDT)
You likely just need to Bypass your browser cache.
I misunderstood when you said "we could mark them all in blue", which suggested to me blue text formatting, not linking. Now I understand that you meant -- that entity names could be linked at all times. This seems like an excessive choice and is not common practice for hyperlinking (which is link on first mention, and not thereafter, though I think you know that). The link you provided seems to be targeted at technical writing for printed works, but still reinforces what I have been saying -- technical terms deserve special formatting/emphasis. I never said that gray shading was some type of standard, though I could see how you could have misunderstood my statement. I said visible marking of significant keywords has precedent in technical writing. Beyond that, the exact formatting is not as critical as long as it is consistent.
With the removal of the gray background shading, and short of any more overwhelmingly compelling discussion, this matter has received enough attention and I consider it resolved. Code tags can be used for entities in any new articles and added to existing ones incrementally. --JeffLane 15:42, 22 Sep 2007 (PDT)
Okay, now that my cache has finally been updated, the code tags are not quite as disturbing anymore, so I consider it an acceptable compromise. I'll start using them, though it'll be a lot of pages to change overtime.
Yes, linking to entities consistently would not have been common practice, but still more discreet than the grey highlighting.
The link I provided also seemed to stress not to overdo highlighting.
...but all's well now. Just a little difficult to write down, but at least it looks decent now. --Andreasen 16:20, 22 Sep 2007 (PDT)
Actually, especially looking at the plural forms (for instance "path_tracks"), this is only half as ugly as gray highlighting, but that might just be my opinion. Users, feel free to add your input. --Andreasen 09:12, 23 Sep 2007 (PDT)