There is no spoon
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.
- 1 Writing Conventions
- 2 Technical formatting
- 3 Properties
- 4 Structs
- 5 Enums
- 6 Delegates
- 7 Methods
- 8 Known Subclasses
- 9 Suggestions
- 10 Related Topics
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.
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
Class Pages Layout
Class pages on the Wiki have this format at the head:
Some clever description of the class.
- 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.
- int anArray
- int X
- int Y
- Where am I?
- float Range
- How far is it?
- First enum value.
- bool OnStupidIdea (coerce string Description)
- Called whenever the author has a stupid idea. (Like now :-))
- float SomeNativeFunction (Class<Canvas> C) [static, final]
- Whatever this one does.
- PostBeginDelete ( ) [simulated]
- Panic and cry.
- Pawn (UT) NextVictim (bool bHungry, optional bool bAngry)
- Well, yeah.
- anything that's left
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 :(
Component by componenent, this is:
- type Name (variable modifiers or replication comments)
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
Suggestion: adding keywords to some pages so they can be found by the search function?