Re-organizing the WML reference in wiki

[Viliam]

I want to make some changes in the wiki that (1) require a lot of work, and (2) maybe some other editors will disagree with. So before I start doing it, I would like to know your opinions -- that is, opinions of people who contribute to wiki.

The WML reference could be "refactored". All information there is important for campaign authors, so it should be more detailed and easier to navigate. My idea is to:

- put each tag on the separate page
- add right menu to quickly jump on any other tag
- write detailed explanation and examples
- provide "see also" links

I made two pages ("advances", "advancefrom") as an example; just copied the information from the original pages. All information on WML tags should be moved to separate pages this way. (Moved, not copied... if information is in more places, it will probably be only updated on one of those places, so the result will be worse.) This is a better example of what I want it to become, but it is in Slovak language -- I hope you get the idea: "campaign".

So, if you have contributed to WML reference on wiki, or you plan to, please write me your opinion on putting each tag on separate page.

[zookeeper]

My idea is to:

- put each tag on the separate page

What? No way. It would make the whole reference mostly unusable or at least incredibly tedious to use.

In fact, what I'd like to do is to cram the whole reference into less pages, something like less than 10.

- write detailed explanation and examples

Good idea. More examples would probably really help.

[turin]

- put each tag on the separate page

No.

Even with this:

- add right menu to quickly jump on any other tag

It would still be a pain to use. It is good how it is - a page for each section. I don't agree with zookeeper, that we should cram it into even less pages, and it might be able to be broken up more, but not this much.
This isn't to say that the sidebar is a bad idea - it isn't. But breaking it up into this many pages is.)

- write detailed explanation and examples

Sounds good.

[Eleazar]

More examples would be very appreciated.
often i look something up on the wiki, read it, and learn nothing. Then i hunt through the .cfgs until i find an example of the WML in action, and then i understand.

Some sort of better indexing/organization would also be a big help.
I usually end up looking on multiple pages before i can find what i'm looking for. The catagories that WML is divided into are not intuitive, at least for me.

[Ranger M]

I don't know if this is possible, but sometimes when searching the wiki, I'm looking for info on a specific tab, to see what I can and can't do in it, but can't find the tab because it could be in multiple places,and I haven't looked in the right one yet, or I accidently skim read over it.

what I would like is a pace with all of the tags listed, and then have them link to the page that has their info on in the wiki. It would also be nice if it jumped to the specific area on the page where it is talked about, but I don't know if that is possible.

EDIT: Oh, and I also agree with Eleazar, I did, and still do, most of my WML checking and dicovering by looking at the WML in other campaigns, simply because I can understand the effect that it has straight away.

[scott]

I suggest you write a campaign first and see what kind of WML reference organization is most useful to you when writing a campaign in terms of what you look for and how you use it.

The biggest problem I think is the three-page division between DirectActions, InternalActions, and InterfaceActions. Some tags are on the last 2 pages when you don't expect them to be.

RangerM, not only is there an index page, there are 2. Right at the top of ReferenceWML. Sanna used grep I think to build hers, and I went page-by-page. We finished at the same time and they're both in there now (hers has keys and tags, while mine is tag-only for quick reference). They are out of date, however. Maybe you could update them!

[Dacyn]

The biggest problem I think is the three-page division between DirectActions, InternalActions, and InterfaceActions. Some tags are on the last 2 pages when you don't expect them to be.

yeah... I designed that system, but it doesn't seem to be very intuitive... here's the basic formula:
- graphics, sound, [message], and [objective]: Interface Actions
- nest tags ([if], [while], [event]), and storing and manipulating WML variables: Internal Actions
- everything else: Direct Actions

[Viliam]

Thanks for feedback!

OK, now I see it this way... if I have enough examples etc to make a separate page long enough, I will make a new page for that one tag; otherwise not.


Once I tried to make a campaign, but never finished it. What I remember from then was that sometimes I was not sure where to look for an "action" (direct, interface, internal), but mostly I was missing code examples e.g. for "filter"... a few guesses were necessary until the game understood what I was saying. But then I learned to look in game data for examples, and this was the solution. Also "AlphabeticalWML" was a page I quickly bookmarked.

[toms]

I guess you know that I´m working on something similar, but I don´t know in how far you want to reorganize the wiki, and I have no problem with let you do that.
(But only actually because I don´t have invested much work)

[Viliam]

What I want is:

1) more code examples (seems like most people agree with this)

2) ability to get to any tag's descrition with one click... that is: I read help for "campaign", with one click I get on help for "scenario", another click to "time", another click to "event",... quick navigation without need to have more windows/tabs open.

The one click browsing can be done by adding a menu (wiki template) with hyperlinks to all tags, to each page. Even if it does not point to separate pages, but rather inside the pages where tags are groupped.


Originally I wanted each tag on separate page (mostly because PHP help does this; and PHP help is IMHO the best help ever written, that is easiest to navigate)... now I see most people are against this. OK, I agree with the majority decision.


Another poll: What do you think about the right menu:
- StatisticalScenarioWML
- UnitWML
Good or bad?

[scott]

Another poll: What do you think about the right menu:
- StatisticalScenarioWML
- UnitWML
Good or bad?

I think that menu is pretty good! However, I am wondering what it would look like if it were not so wide - maybe cut down by 1/3?

As for examples, you might write a scenario that uses all of the common tags in their typical usages. It seemed to work ok for the MP example scenario we made (it only showed units, messages, and labels - common MP stuff). Once it's written you can figure out how to link to it.

[zookeeper]

The CSS must definitely be tweaked to accommodate that side menu, since there's plenty of empty margin on the right where to position it to.

[Viliam]

However, I am wondering what it would look like if it were not so wide - maybe cut down by 1/3?

Just do it, it's a wiki
Template:WML Tags

I was playing a bit with it... the wide column consumes too big part of the page; the narrow column is too long and looks ugly... hard to find a decent width. I tried it horizontal instead of vertical, but then it looks huge and ugly. I hope font 7pt is legible... 6pt is too small, with larger fonts it takes too much place...

[JW]

I think this will greatly help the number of people that contribute meaningful things to the project. I didn't learn much from browsing the pages before, so I wish you the best of luck.

[scott]

Hmmm.... This is tricky. The narrower menu looks good with the monobook skin, which is my setting, but not necessarily better with the Glamdrol skin (everyone's default). In the Classic skin, the width is ok but the font size is horrendous. Can you change the template based on the user's skin? The small font looks good in Safari but poor in Firefox. Don't know what to recommend, so, uh, good job!