Legacy:Guidelines On Page Links

From Unreal Wiki, The Unreal Engine Documentation Site
Jump to navigation Jump to search

It's important to keep the wiki rich in links. It makes it easier to find things without having to use the search function, and it reduces the possibility of people duplicating what's already written (although a new slant on things is often good). Wiki:LinksAreContent.

Feel free to add or discuss guidelines here.

Places to link from

When you create a page, you need it to be linked from other pages so people can navigate their way to it. Here are some suggestions:

  • The main topic pages that are listed on Home Page.
  • For tutorials: Mapping Lessons or UnrealScript Lessons
  • The class pages. For example, a list of "Tutorials which use this actor"
  • Other pages on the same subject. For example, if you write a tutorial on advanced doors, put a link to it on other door tutorials, so readers can easily read more on the subject.

Try to avoid hidden links, unless they make a sentence really clumsy. Write [[Legacy:Actor|actor]]s rather than [[Legacy:Actor|actors]]. This helps quickly see what links are when housekeeping.

Links on a page

Broadly speaking, there are 4 places to put links on a page: in the text of the page, in the Related Topics section, in the External Links section, and the category footer.

Pages to consider linking to

  • Class pages for the actors you write about. For instance, breaking walls and glass involve two different actors, so make a link. If the page doesn't exist yet, consider making a brief start on it – adding a link back to your page, naturally. Make sure you name them exactly as they appear in the browser.
  • Technical terms, like Semisolid, HUD (UT), red builder brush or pivot. Make the most of the wiki system and link instead of explaining the terms yet again. The text flows more cleanly and beginners can follow the link if they need a detailed explanation.
  • Basic procedures, like Making a 2D Shape, Texture Import and Export or Actor Overview. Avoid duplicating content on many pages: see Category:Legacy Basic Procedure for the current proposal on this.
  • Other tutorials. Suggest some prerequisite tutorials, and maybe some tutorials for advanced reading in the Related Topics section (see below). Give the reader some places to go to.
  • Topic pages such as Mover Topics or Lighting.
  • Menu names give full menu commands and link the menu name, like this: "UnrealEd Main Menu -> File -> New". See UnrealEd Menus for the list of page names.

General guidelines on links

  • Don't overdo linking. That's the extreme opposite of not linking at all. It's most convenient for authors and readers alike to link only the first occurrence of a term in a logical unit (a section of a tutorial, for instance). Since links stand out visually, they have the potential to disrupt the reader's flow and make reading a long text a pain when each and every sentence has one or more links. For example, if you mention "PlayerStart" several times, link only the first one, or the one that's relating to something technical, at a point where the reader might logically want to read up on the specifics.
  • Connect related pages. Click on the page title to do a search on the page name. If you find pages which you think are related, create a link both ways.
  • Link terms in their singular form and not their plural form; for instance, link zones, not zones (and not zones either). That will make it easier to link to that article in a sentence like "create another zone."
  • On the other hand, link duplication is good. It's easy for n00bs to land on technical pages. Give them a link to something simple, like Types of Trigger on the Triggers (UT) class spec. The hierarchy is quite vague – one page may get a link on several topic pages.
  • Avoid abbreviations. Their meaning may be clear to you, but abbreviations have the inherent risk of being ambiguous and confusing not only to newbies. Very common acronyms like HUD (UT) and BSP have their own pages – link to them. If you use an abbreviation, give the full term in parenthesis the first time you use it on a page, like "OCD (Object Collision Detection)" or vice-versa, "Object Collision Detection (OCD)."
  • No "here" links. Linking along the lines of "Click here to get a list of contributors" is very bad style and detrimental to readability. If you by any means can, link the actual page titles.

Related Topics links

Most pages have a section at the end titled "Related Topics". List here all the links which don't fit into the text of the page.

It's helpful to commment on how the links relate to the current page.

External links

External links are altered and re-routed all the time because people change servers, or lose interest in maintaining the structure, or eliminate the page because it becomes obsolete. It might be an idea to occasionally check external links.

On the other hand, the interest of 'wiki' is precisely to avoid links at all costs and make the most comprehensive thing in one place.

Category links

Links to category pages are usually put at the foot of a page, beneath a rule-off ('----' in markup). However, category pages that count as a related topic, eg "Category Mapping" can go in the Related Topics section.

T1: So does this mean we should always put the link in both places, or choose based on the situation? I vote for the "both places" choice if it's up for vote.

OlympusMons: I thought the Topics on whatever would go in the related topics where the catergories would go in the well catergory links unless the catergories is moved above the related topics. Preferrably Id like to see related topics at the tops of the page with the catergories on the bottom but this isnt a huge issue. I think actually getting the main pages for everything to some sort of complete status would be then we can discuss formatting once ut2k7 is alittle closer. Also I have seen pages with links up the top, they are under required reading.

Tarquin: I'd say if the category link is in the related topics, only 1 copy is needed. But having 2 won't do any harm :)

SuperApe: I agree that it can be considered a Related Topic, but if all the other pages are formatted one way and we begin to subjectively change some of them, what's the point? And where would the line be drawn? To me, they seem to be nearly in the same location on the page; near the bottom along with External Links, etc. They also seem to be a separate kind of page, one that uses the MAGIC keyword to group all pages, but itself is not a page containing topic info. You're right, there's no harm done either way, but if we're going to have a standard or method to this madness, I vote that it stay consistent. (at the bottom, under a rule-off and grouped with other category and wiki tags.) /my $0.02 (Btw, I've recieved an email from Ch3z, and from that it doesn't sound to me like he's interested in coming back. I dunno.)

InterMap

We're running an intermap: that means that certain wiki-type links lead to other Wiki sites. A wiki link with a prefix and a : separator creates an interwiki link:

[[Wikipedia:fish]]

See InterWiki for more.

Note the prefix is (annoyingly) case-sensitive. The most commonly used ones are:

  • udntech
  • udncontent
  • Thread
  • Posting
  • Wikipedia
  • Wiki
  • UseMod
  • MeatBall