Legacy:Guidelines On General Style
This page defines (and debates) general style for the project. See also:
- Guidelines On Page Links for more on where to put links and what to link.
- Guidelines On Tutorials for tutorial conventions and using Category:Legacy Basic Procedure pages to make writing tutorials simpler.
Contents
Writing Conventions
Avoid abbreviations. Their meaning may be clear to you, but abbreviations have the inherent risk of being ambiguous and confusing not only newbies. Very common acronyms like HUD and BSP have their own pages – link to them.
Text formatting
Some simple guidelines:
- use '' and ''' wiki-style formatting instead of B and I tags. Use ''''' if you really must, but ask yourself: why does it need to stand out so much?
- don't use the U tags, it can get confused with links.
- don't use font colours.
And some reasons for them:
In general, ask yourself the above question: why does it need to stand out so much? It's up to the reader to give your article his/her attention, not up to you to grab it. If they are reading your page, then they want to learn about what you have written.
Don't overuse emphasis. It loses its effect and makes articles hard to read. Some things will stand out of their own accord, if you use the agree formatting conventions:
- class names and window names (because they're a link – or should be)
- menu commands and properties (because the -> glyph is distinctive)
A fact that there's no escaping is that most of the procedures described on the site involve many complex steps. Readers of this site are aware of this, and will read carefully – if they don't they'll soon learn.
Consider alternatives to lots of bolding:
- a bullet list
- a table, for example if an actor needs lots of properties setting
Technical formatting
Class Pages Layout
Class pages on the Wiki have this format at the head:
<wiki>@@UT/UT2003 :: Actor >> foo >> bar (Package: package name)
Some clever description of the class.
Properties
Interesting Group
- string Property1 [replicated to clients]
- That's some mighty interesting property.
- Pawn (UT) Property2
- That one might be less important.
- class<Actor> Property3 [const]
- Not changable but still not neglectable.
Not-so-interesting Group
- int anArray[4]
- Dunno.
Structs
SpecialStruct
- int X
- int Y
- Where am I?
- float Range
- How far is it?
Enums
EThisAndThat
- TAT_One
- First enum value.
- TAT_Two
- ...
- TAT_Three
- etc.
Delegates
- bool OnStupidIdea (coerce string Description)
- Called whenever the author has a stupid idea. (Like now :-))
Methods
Native Function
- float SomeNativeFunction (Class<Canvas> C) [static, final]
- Whatever this one does.
Events
- PostBeginDelete ( ) [simulated]
- Panic and cry.
Other Functions
- Pawn (UT) NextVictim (bool bHungry, optional bool bAngry)
- Well, yeah.
Known Subclasses
- anything that's left
Category:Legacy Class (UT)
Category:Legacy Class (UT2003)
</wiki>
Question: Should we farm out the above to a separate template class page? Would it be clearer?
Comments on a better layout are welcome, but we should stick to one layout throughout the site to to keep the confusion at a minimum level.
Uncommon: What about having a way of coloring variable and function declarations so that the names stand out more? I've been leaving out the types and parameters because I think having all that stuff makes it harder to read. Maybe leave the name in the normal color and make the rest gray.
Tarquin: Could be done, I suppose, by searching for keywords within a ;: wiki tag. Wookee scares me though :(
More: Guidelines On Technical Names
Component by componenent, this is:
Class box
property lists
- type Name (variable modifiers or replication comments)
- description
Class Boxes and Property Settings
Giving a list of properties the reader should set on specific actors. No set standard as such, though you might want to use something like:
- Trigger A : Events -> Tag = 'foo'
- Monster B : Movement -> Something = 567
Suggestions
Search Keywords
Suggestion: adding keywords to some pages so they can be found by the search function?
