Recap improvements needed in the Wiki site - Where?

[Gig]

On hindsight, I'm not sure if I would like the use of "disable_" and "replace_". Because the issues with the map are still there, and those are things which will possibly never be reported. Then, after the releases, we have the load of bullshit we have to deal with.

Uh? I'm almost still sleeping this morning... Zzzzz... So excuse me...

I have not understood your post... are you talking about a specific map? What's the link between some admin customization capability (similar to the ability of changing weapon respawn times, or to modify gravity, speed and knockback... "powerful" customization features that may however make the map unplayable if used badly), and the comments that arrive on the forum after an OpenArena release?

[Neon_Knight]

I was using "the map" as something generic, any map would fit the "the map" statement. About my worries with _replace and disable_, the thing is that, for example, a problem with the Railgun in a space map possibly won't ever be reported because they're already playing a "modified" version of the map.

[Gig]

Well, nobody forces server admins to actually use the feature. We're just saying that it does exist.
I can guess that only a relatively small number of servers will actually use the feature, even now that it is better documented... people would continue to have more chances to play on a "plain" version of the map than on a "admin-replaced-items" version of it. Of course, I'm just guessing...

By the way, I just added a thing to the tips at the end of the page: (DO NOT LINK) h t t p s : / / openarena . wikia . com/index.php?title=Disabling_and_replacing_items&diff=14769&oldid=14768

[Gig]

Hi! It was a long time I wanted a list with links to "app stores" and "ports" in general, to let people know for which other platforms the game is available... and for us, to have an idea about who re-packages and re-publishes the game.

So, I created this page:
(DO NOT LINK) h t t p s : / / openarena . wikia . com/wiki/Ports_and_markets

ANY IDEAS? SUGGESTIONS? COMMENTS??????

I have not yet linked it from other pages, so we can easily rename it if necessary.

[Gig]

No comments, guys? 

[Neon_Knight]

Ask pelya or gamesboro.

[Neon_Knight]

We've talked about the situation with the manuals in the past. So far they have a bunch of problems. They're as complete as possible, and Gig has done an over-excellent work with them. Yet, they are extremely hard to read. Completeness is good, but stops being good when everything else has to be sacrificed in order to achieve it.

I've identified some problems:

• They have info not related to OA but related to mods for OA/Q3. If the manual is about the base game for players, then such notes IMHO have no place there. They could go to the mod's page, for example.
• They have a lot of info about the console commands, giving the impression that OA is heavily dependant on the console, which in practice isn't THAT true. Also, most of these mentions are only relevant for server admins.
• They have mentions to the mapping side. This should be left to the mapping pages, as they have no relation to the game itself except for it's development. But since the manual IS for players, they aren't relevant for this area.
• The classic problems: walls of text, parabombing, small texts breaking the lecture in the paragraphs...

I've been thinking on a solution to keep the manual's pages on an acceptable reading level and preserving those notes by creating appendixes for those pages. I've started with the DO NOT LINK[/b]) h t t p s : / / openarena . wikia . com/wiki/Manual/Weapons]Weapons page, DO NOT LINK[/b]) h t t p s : / / openarena . wikia . com/wiki/Manual/Weapons/Appendix]here's the annex.

What do you think?

[Gig]

In general, as I said DO NOT LINK[/b]) h t t p s : / / openarena . wikia . com/wiki/Talk:Manual/Weapons#My_edits]in the talk page of "Manual/Weapons" page in other words (please read there, too), I don't think that there is a precise border to say when a player should begin to mess up with console, or should ignore it. Console allows to do thousands of things in this game, and I think we should not scare the user making him think it's something dedicated to server admins only.... using console commands to activate some different game option or to make his weapon show different effects is something normal in this game.
However, I checked at your work, it isn't bad. I did some little fixes to it, but I can guess in general it's okay.   But maybe, before appying such huge changes to a page in the future, we may discuss how to organize its "appendix" page. In this case, I'm not completely sure the approach you used for its sub-sections (mod-related, cvars, other) is the best... maybe something more similar to the structure of the main page would have been better? I'm not sure. Also, maybe we may somehow specifiy for a few topics of the main page that it's advisable to check the appendix about it?

[Neon_Knight]

I'd restrict the appendixes to the manual pages.

Basically, a manual page is dedicated to a specific subject. It should be focused only on that specific subject, with nothing getting in the way of that specific subject.

Mentions to mods are useless since that stuff isn't present in the base game, regardless of what the people wants. They should be kept to those specific mod's page or, at the very least, be moved to the annexes.

Mentions to mapping are also useless since it isn't related to playing the game but to developing content to it, which is outside of a player manual's scope. Those bits should be moved to the development/mapping pages. (Also, I've realized that modifying the property of any item do mess with the gameplay, so it's safe to say that it enters into the "bad practices" area in the same way a "goto" or "break" statement is a bad practice in regards to programming.)

A player shouldn't also have the need to mess with the console in order to enjoy a game. OA is already "complete" and enjoyable without the need to mess with the game's console. Too many mentions to the console gives the contrary impression, that messing with the console is mandatory in order to enjoy OA, which isn't really the case.

[Gig]

Basically, a manual page is dedicated to a specific subject. It should be focused only on that specific subject, with nothing getting in the way of that specific subject.

Well, in theory, if the subject is "weapons", everything about weapons may fit. I mean, there is no reason to put something about how to change screen resolution (just an example), but mentioning that a player can change the look of his own railgun effect, while talking about the railgun weapon, seems coherent to me... then, if possible it's better to place a link to the page that actually mentions how to change it (e.g. "Manual/Player settings")... but sometimes there is no another page that hosts that specific info, and would have little sense to appositely create a page for that, hence a foot note or something in these new "appendix" pages may fit well.

Mentions to mods are useless since that stuff isn't present in the base game, regardless of what the people wants. They should be kept to those specific mod's page or, at the very least, be moved to the annexes.

I can guess Appendix page can do the trick (previously made by a parenthesis or foot note...) of briefly mentioning a certain feature does exist in a certain mod, giving a link to the page of the mod (where, of course, the feature can be better explained).
Note: if there is too few of such stuff to create a proper "appendix" page, one can just keep the foot note in the meanwhile. I mean, if I have to create an Appendix page for two or three short notes only, it's better I keep them in the main page. If there are a lot of notes, like in the Weapons page, an Appendix page can be welcome.

Mentions to mapping are also useless since it isn't related to playing the game but to developing content to it, which is outside of a player manual's scope. Those bits should be moved to the development/mapping pages.

As I told before, the problem is that we don't have a real "mapping course", so sometimes the problem is which "landing" page to choose...
Ideas are welcome.

(Also, I've realized that modifying the property of any item do mess with the gameplay, so it's safe to say that it enters into the "bad practices" area in the same way a "goto" or "break" statement is a bad practice in regards to programming.)

Uh? I lost a bit with this... are you saying that using the game's customization capabilities to create your own favorite settings (e.g. adjusting gravity level, enabling "vampire mode" or preventing grappling hooks from spawning) is always (or almost always) a bad idea? Uhm... this sounds a little strange to me. This game has been quite customizable since the beginning...

A player shouldn't also have the need to mess with the console in order to enjoy a game. OA is already "complete" and enjoyable without the need to mess with the game's console. Too many mentions to the console gives the contrary impression, that messing with the console is mandatory in order to enjoy OA, which isn't really the case.

The base game is very enjoyable also without the need to use the console, true. But there are also many cool features which are not available in the UI at all, and many other that are just more comfortable to set through the console. Console isn't evil, and anyway we need to write down console commands somewhere (probably they are too many to have a single page with all commands in it, with completeness and logic order. An "alphabetic full commands list" page like this web page can be very useful in some situations, but really inadequate in others. This is also one of the reasons maybe we may think again about the best section organization of Manual/Weapons/Appendix page: maybe a "logical" separation may be better than a "category" separation?). What do you propose, splitting each manual page in "standard" and "advanced" sub-pages?  

[fromhell]

A manual doesn't need complete and elaborate explanations for every little section. This is a player's manual; not a man page.   Information overload can be had elsewhere (i.e. advanced sections)


More "This gun shoots bullets in rapid succession", less "This gun is a hitscan weapon that deals 15 damage and fires at a rate of 0.1 seconds"

[Gig]

A manual doesn't need complete and elaborate explanations for every little section. This is a player's manual; not a man page.   Information overload can be had elsewhere (i.e. advanced sections)

"Man page" does not mean "manual"? So the phrase says something like "A manual is not a manual"?   I can guess with "man page" you meant "an advanced manual", or something similar...

Okay... we may try to divide something in "for beginners" and "advanced", somewhow... But also disassembling informations, placing them in different places with no logical order, may not always be a good idea. That's the reason I suggested re-organizing the sections in Weapons/Appendix page to follow a logical order similar to its main page, instead of dividing into "anything mod-related", "console commands in random order" and "other" sections; I'll try to do that in the next week. Note: of course, also letting stuff totally undocumented would not be a good idea, too: "advanced manual" stuff is however needed somewhere.

DO NOT LINK[/b]) h t t p s : / / openarena . wikia . com/wiki/Manual/Weapons/Appendix]Manual/Weapons/Appendix page "saved" something like 11KB from its main page, so I can guess it can actually make its main page faster to read, so it can have sense. Maybe we may even think about moving the "weapons comparison table" from the main Weapons page to the Appendix, if you wish...

But DO NOT LINK[/b]) h t t p s : / / openarena . wikia . com/wiki/Manual/ESC_menu/Appendix]Manual/ESC menu/Appendix instead, "saved" only 708 bytes from its main page... it seems to me it does not justify the need for a separate page: DO NOT LINK[/b]) h t t p s : / / openarena . wikia . com/index.php?title=Manual%2FESC_menu&diff=15137&oldid=13504]looking at the changes it did in main page, it seems to me those few, short infos may have continued to live were they were without adversely affect the ease of reading of the page. I propose to UNDO those changes, what do you think?
"If it's a console command, it automatically goes to the appendix in any case"^[1] does not sound very smart, to me. I think if an Appendix page is too short, it's better to keep its stuff in the main page (foot notes may help)... although it's not easy so say a precise limit... 3/4 KB minimum? I don't know, I prefer good sense over a strict rule.

About DO NOT LINK[/b]) h t t p s : / / openarena . wikia . com/wiki/Manual/Player_settings/Appendix]Manual/Player settings/Appendix, instead, for the moment I only gave a very quick look to it... but however I see that it "saved" something like 8K bytes from its main page, so I can guess it's worth of existing as a separate page.

PS: This "Appendix" scheme, while useful for some pages, is not applicable to some other pages, such as DO NOT LINK[/b]) h t t p s : / / openarena . wikia . com/wiki/Manual/Graphic_options]Manual/Graphic options: if you think it's necessary, we may try to re-arrange the page to follow some more logical or importance order (or splitting into "commonly used settings"/"other settings" or "HUD-related settings"/"world-related settings" subsections or subpages?).... but separing console commands from the sections where we explain their effects and option names in the GUI (if available) would be a mess.

However, these are works which require time and in this period I have very little.


^[1] Nobody actually told these exact words, I know... but that's the feeling "ESC menu Appendix" page gave me.

[Suicizer]

A manual doesn't need complete and elaborate explanations for every little section. This is a player's manual; not a man page.   Information overload can be had elsewhere (i.e. advanced sections)

More "This gun shoots bullets in rapid succession", less "This gun is a hitscan weapon that deals 15 damage and fires at a rate of 0.1 seconds"

Keep in mind a manual should not state the obvious, rather the informative. That a weapon would be succesfull to shoot rapidly is quite senseless to know if you've started OA, took the MG for example and hitted the fire button. To know it fires 0,1 bullet per second would be more useful to know as most people won't take the time to check that and actually count each shot per second.

You could also use a "slidebar" (I don't know how it's called specificly but  I mean a piece of context which only appear on the same page when clicking on a link) to hide more advanced information.

[Neon_Knight]

But there's a huge difference between it and mentions to mods (which have no true relation to OA other than being external modifications) and mapping (which in a manual oriented towards players, not developers, have no relevance). That kind of info isn't needed in a player-oriented manual.

Oh, another error I've found in some places: biased/subjective information (the most common being "X is nice") makes the user manual to look more like a personal page rather than a wiki. That should be avoided.

[Suicizer]

But there's a huge difference between it and mentions to mods (which have no true relation to OA other than being external modifications) and mapping (which in a manual oriented towards players, not developers, have no relevance). That kind of info isn't needed in a player-oriented manual.

Oh, another error I've found in some places: biased/subjective information (the most common being "X is nice") makes the user manual to look more like a personal page rather than a wiki. That should be avoided.

Screw mods, they can make their own page. After all, ID Software aren't creating the wiki for OA are they?

[grey matter]

A manual doesn't need complete and elaborate explanations for every little section. This is a player's manual; not a man page.   Information overload can be had elsewhere (i.e. advanced sections)

"Man page" does not mean "manual"? So the phrase says something like "A manual is not a manual"?   I can guess with "man page" you meant "an advanced manual", or something similar...

At least with Unix, the man pages are quite spot-on, e.g. "man ifconfig" does not explain how (insert protocol here) networking works, just how ifconfig works. If you don't know when to use a tool it won't help you to know how you'd use it.

[Gig]

A manual doesn't need complete and elaborate explanations for every little section. This is a player's manual; not a man page.   Information overload can be had elsewhere (i.e. advanced sections)

"Man page" does not mean "manual"? So the phrase says something like "A manual is not a manual"?   I can guess with "man page" you meant "an advanced manual", or something similar...

At least with Unix, the man pages are quite spot-on, e.g. "man ifconfig" does not explain how (insert protocol here) networking works, just how ifconfig works. If you don't know when to use a tool it won't help you to know how you'd use it.

But if you need, general networking manuals do exist. This is the only manual about OA....
Side note: some OS "helps" that just mention allowed parameters without even spending ten words to briefly mention what the command does in general make me get angry.

PS: Nobody yet told me if I can re-unite the "ESC menu appendix" with its main page, due to that appendix page being too small to have sense as an independent page (IMHO!).

[Neon_Knight]

A general appendix, then? There's a reason of why books have such section.

[Gig]

You could also use a "slidebar" (I don't know how it's called specificly but  I mean a piece of context which only appear on the same page when clicking on a link) to hide more advanced information.

In wikipedia, there are templates to make "boxes" that show only a title, that user can expand/collapse at willl (here: Template:Hidden on en.wiki)... Years ago, I tried to import it into our wiki, but I did not succeed... however I later started using "foot notes" for extra notes ("ref"s), but now it looks like someone wants something more drastic...

A general appendix, then? There's a reason of why books have such section.

I fear this would not be easy to apply. A wiki is not a book... I'm trying to imagine how to manage a such thing, but I don't see a practical way.   Maybe a page with all OA console commands may be a sort of one of those appendix, but a page with all console commands would not fit all the needs... we still would need mentioning the commands also in the pages where you talk about the features which use them.

However, there are some pages where a page-specific appendix ("Manual/Page/Appendix") like you did for Weapons may be worth of existing, for the sake of making reading the main page easier (maybe the appendix division in sub-sections may use a more "logic" than "category" criterion, but I already said this and I have not yet had the time to try to apply it to that appendix page)... but not all manual pages require an appendix, IMHO (and, except real size/readability problems, there is nothing wrong in mentioning the console command which controls a certain feature in the same page where you explain that feature... IMHO). About the "ESC menu" page, I still don't see the reason for DO NOT LINK[/b]) h t t p s : / / openarena . wikia . com/index.php?title=Manual%2FESC_menu&diff=15137&oldid=13504]this edit, which created DO NOT LINK[/b]) h t t p s : / / openarena . wikia . com/wiki/Manual/ESC_menu/Appendix?oldid=15138]a very small appendix page.

[Neon_Knight]

Such drastic measures wouldn't be needed if the pages weren't bloated with unnecessary data which makes those pages hard to read and can be placed somewhere else.

If the menu already allows something to be done, the only necessary data is the menu option itself (NOT the console command) and what changes it does to the game (without even mentioning mods or other console commands as well). That's it. Move on. Remember the K.I.S.S. principle.

And even in the cases where something can be done console-only, shouldn't be better if the manual (not the wiki) doesn't spoil everything the game has to offer? No game manual ever has done that; I don't see why OA should.

[Gig]

But what about freedom of choice? People have to know they have alternatives, to be allowed to use them.

However, some pages actually have some stuff that has sense to be moved to a separate page, but the "ESC menu" one is not one of them, IMHO...

Reading just one extra line of text and learning that I can write "/callvote map wrackdm17" in a quarter of the time it would take to do it by using the ESC menu sounds useful, to me.

PS: "to spoil" (like in "spoiler") may be related with "reviews" and "plots". It seems to me it has nothing in common with "manuals"... I expect a manual to tell me what I can do and how I can do it... If I want a "spoiler-free review", I will search for a "review" in the first place... Maybe I am missing something...  

[Gig]

Just a note: that "someone" word I used a few posts above had no negative intention, it was just to say "some users".

You know, after re-reading something, one may realize he wrote something that may be misinterpreted...

[Neon_Knight]

But what about freedom of choice? People have to know they have alternatives, to be allowed to use them.

Reading just one extra line of text and learning that I can write "/callvote map wrackdm17" in a quarter of the time it would take to do it by using the ESC menu sounds useful, to me.

They can (and should) find them in other pages on the Wiki. Manuals should have basic info.

However, some pages actually have some stuff that has sense to be moved to a separate page, but the "ESC menu" one is not one of them, IMHO...

Again, the stuff moved to the Appendexes can be located somewhere else on the Wiki.

PS: "to spoil" (like in "spoiler") may be related with "reviews" and "plots". It seems to me it has nothing in common with "manuals"... I expect a manual to tell me what I can do and how I can do it... If I want a "spoiler-free review", I will search for a "review" in the first place... Maybe I am missing something... 

Yes, by way of being a manual, telling the player of all the things you can do in the game leaves him/her with the impression that there's no need to play the game to know all the things which can be done on it. And, from my humble point of view, this is very bad.

[fromhell]

Quake III Arena provides a nice example. They have a pretty manual that's exceptionally light on the technobabble, and they have a separate readme document elaborating on many settings and commands (especially on how to use bots to advantage in team games)

[Neon_Knight]

I'm collecting links in order to create OA's own mapping manual. Right now I'm storing them in this page: (DO NOT LINK) h t t p s : / / openarena . wikia . com/wiki/User:PumpkinKnight/OA_mapping_tutorial_notes_and_misc

The content table for that page also holds a possible index. Is it OK or should I go deeper in the division of topics?