User talk:Adelas/Sandbox-itemboilerplate

Very good start! I added a couple of comments at the beginning... Ignore my attempt to "align" things (which I reverted). I forget about a problem which existed with Safari... the "preview" window and the "edit" window display things differently, which turns out to be a bug with Safari.

Some thoughts:

1- There should probably be some kind of text ahead of the parameters box that says something to the effect ...

This page can be used to automatically create wiki pages for multiple different "categories" -- Quests, Items, Skills, Crafts, Recipes, ...

Fill in the blanks as appropriate for that category.

The values for items here can be found by "mousing-over" the item in-game and recording the information from the "pop-up" "tool-tip" box that appears.

2- We should probably develop some sort of coding to indicate which parameter applies to which category... and then group them together

3- Is this whole effort even necessary -- this might actually be creating more problems by virtue of its complexity than it solves. Trying to figure out which parameters are appropriate for which type thingie is hard. Especially when many of the "parameters" are seriously subject to interpretation... "barter" being one that comes to mind.

4- What problem is this combined page it trying to solve in the first place? Wm Magill - Valamar - OTG/OTC (talk) 17:33, 16 October 2011 (EDT)

5- Bind... also "Bind to Account" (store items in particular, but some lottery winnings also. 6- all category items should have same comment 7- Duration, expiration, etc all "used" to take 2m or 2s as values (still working my way down the page.) Wm Magill - Valamar - OTG/OTC (talk)

1. Good point, that info probably fits better in front of the page than after it.

2. Not my area of expertise :)

3a and 4: I wrote an answer all willy-nilly in response to yours and then tried summing it up and it got repetitive. If this seems terse, it's because I started from scratch instead of quite responding to your questions. So don't read anything into it. Here you go:

I saw that you and Seth were talking about the need to explain the parameters, and since that's a cause that's near and dear to my heart, I thought I'd try my hand at it.

When I use the page "Create New Item", I want to see:

Boilerplate box with definitions
Boilerplate add-on boxes with explanations and examples
The Edit Box with a clean template for me to type everything into.

Most importantly, I think that the box on the create new item page needs to have the answers in it, so that the person creating the new page doesn't HAVE to open a separate tab to learn the right way to fill it in.

I am by no means a code monkey, but I would say I have intermediate understanding of the code here. I know it the way I know Spanish; I couldn't remember enough vocabulary or grammar to craft my own sentence, but I can read Spanish at maybe an elementary school level, because I understand the framework and I have enough knowledge of latin roots that I can get the underlying meaning of words I don't technically know. Same here - I know some html, I played with CSS and DHTML about a decade ago - I can usually puzzle it out, especially when I get to use the preview window to know whether I screwed something up by leaving out a | or an extra colon or something.

Now, when you get someone here at my level, or lower, just someone who plays the game a lot and has a BASIC understanding of how code works, comes and sees these parameters, and doesn't know what to put in them. If the person creating an item for the first time REALLY understands what belongs on each line, I think they're more likely to enter the information correctly and completely the first time, reducing the need for corrections/adjustments afterwards. Not eliminating the need, I know. But I know that there have been times when I personally created an item and figured "well, I'm not sure if this answer goes here" or "did they mean for me to put a 'yes or no' or is it 'yes or blank'?" so I left certain parameters untouched, when I had the game info and (having the right wiki knowledge) could have filled them in properly.

On top of now knowing what the parameters mean, someone that is a casual user of the wiki might not know where to look to FIND the parameter definitions. And, frankly, they might not be DETERMINED enough to go find the page, open it in a separate tab, and switch back and forth as they edit their new item.

I didn't know this page: Template:Npcbox existed (I found it later on), but basically THAT, the full explanation of EVERYTHING on the page, is exactly what I wanted to do for the item page.

I do like how on the Template:Npcbox page, there is a standard verbal explanation (Meaning Behind the Parameters), which allows the text in the template to be more terse and clean. However, I think that would make the Create New Page even longer and MORE unwieldy; perhaps the solution is to have a special page on "Item Creation Guidelines" (sample name). The boilerplate with BASIC explanations (similar to NPCBOX) appears in the Create New Item edit page, with a link at the VERY top of the page that say "for more detailed explanations on what to put in this template, click this link". And then the link goes the guidelines page, which shows the boilerplate AND the nice "Meaning Behind the Parameters" section.

FWIW, I know that what I made here is very complex - it's a wall of text which usually makes my eyes gloss over. (Incidentally, that's why I didn't repeat the same information on all five category lines). But I think that the payoff in long term accuracy and efficiency is worth having to scroll an extra turn of my mouse wheel to get down to the edit portion of the page.

3b. If we don't have agreement on what the parameters mean, I think that needs to be duked out and then documented clearly. Mushy definitions are VERY, VERY bad for pages that can be edited by just anyone.

Why the surrounding markup?

I have a question of my own. Why did the original boilerplate have the <!-- markup on every line? It adds to the visual clutter, and I see the Template:Npcbox doesn't have that... I'd like to remove that part of the markup, but there could be a good reason NOT to, that I just don't know of. -Adelas (talk) 18:53, 16 October 2011 (EDT)

Someone who really knows the history maybe could answer... but I would assume that the <!-- entries are because the original pages WERE included (transcluded?) in the display and the comments were causing the parsing of the templates to fail. Today, it might be an artifact of past history or there might still be pages "that work that way." I suspect that Amphoras or LOTROADMIN can answer if they are (or ever were) necessary. Some things like that simply happen because someone does it that way and everybody copies them. Wm Magill - Valamar - OTG/OTC (talk) 22:06, 16 October 2011 (EDT)

Ahem, forgot I was going to answer this earlier. The  is nomally used to denote a comment. I assume it has been used here to show the difference between what is just extra information, and what will actually appear in the edit box. For example, on this line: | name = {{subst:PAGENAME}}  the {{subst:PAGENAME}} will appear in the edit box, but the "no need to change this line, it will be filled in automatically when the page is saved." will not. I assume this is the reason it has been used, but its not strictly needed and won't break anything if its removed. Amphoras (talk) 12:42, 17 October 2011 (EDT)

So, that's good to know then. I think if this project moves forward, I'd like to remove the markup, then. (From the version that is simply an "explanation" copy.) -Adelas (talk) 13:04, 17 October 2011 (EDT)

lets back up a bit...

I agree with the 3 things you use the page "create new item"
Is this page that we're trying to document ... an updated version of the "Create new item" page Create_new_item ... or is it a "Create multiple different things" page? I'm not certain I'm understanding our starting place. Somehow I thought that ?Sethladan? was creating a new "thing" that combined multiple different things. ~~User:Sethladan/Sandbox~~ - don't think I understand what was happening here.
Your description of Spanish is my experience with Computing and the Web... 30 years as a System Administrator at the "Enterprise level" -- i.e. I Administered Systems, not programmed them -- had a staff of programmers for that. I got involved in the WWW movement when Tim started it... working with an undergrad student at the time, put up the 8th WWW server in the world. (at upenn.edu). So all my HTML and etc knowledge is serious OJT stuff...
Template:Npcbox WOW! that's cool... never saw it before. I've only been playing on the Wiki here now since May of this year (2011) and one of the first things I encountered was the fact that the "help" page documents didn't document what was being created. I forget which one I got started with (was working in the Moors as there were almost zero FREEP entries), but ultimately wound up "fixing" the Quest Boilerplate page only to discover that changes to it never had anything to do with the content of the "edit box." Then got shown the Template business.
Related to Template:Npcbox -- sadly it is not "complete" -- in that there is a whole parallel "tree" -- Template:Infobox MP-NPC --- which leads into what Zimoon has been talking about concerning Categories in general...
Your description of many "would be contributors" is probably 100% correct. Creating or even updating many pages is anything but "simple."
It's going to be hard to avoid "a wall of text" when the basic "infobox" is itself a full page in length.
Mushy definitions #1: What is a "[[Zone]]" vs an "Area" -- Areas are defined, but Zones are not... yet Zones are used and referred to constantly. (and no, right now I can't recall where/why this confusion exists.)
The "Create new item" page Create_new_item -- is likely the ?most? complex effort one might undertake on the Wiki. This might be something that needs to be restricted to Ninja level or ??? and probably should have a pointer/warning on the starting page ... to check the "Item Creation Guidelines" page: Help:Items -- which goes back to #4 above... that page doesn't say much... and for whatever reason, the link at the bottom is no longer existent. (It really doesn't seem to have been renamed.)

Wm Magill - Valamar - OTG/OTC (talk) 22:06, 16 October 2011 (EDT)

me again

I didn't have a good reason for a separate section, except that I visually prefer the headers like this instead of responses using :, ::, :::, :::::::, and since it's a talk page, i can do it however I want!! muahahaha!

So for further clarification because, whoops, I never actually said it this way: You're right that what I've done is related to Create_new_item. When I click the button on Create_new_item, that form creates a page (with the appropriate name), automatically starts me editing it, and up at the top of the screen, above the edit box, like a magic preview boilerplate, is....... THIS.

The thing you see here in my sandbox, is what appears above the editing box on the new page. (well, technically this is what I WISH it looked like; the real one is almost empty.) It automagically appears almost like a preview of what you're editing, although once you truly hit preview, it disappears.

So, I'm not talking about adding anything to Create_new_item itself, but just updating the appearance of that "magic preview boilerplate". I think that MAYBE it's being transcluded from the actual boilerplate page? And if that's so, there definitely should be a CLEAN version on the boilerplate page, POSSIBLY followed by this filled-in version, or a cleaner version thereof. And possibly linked, as I said before, to a very, VERY detailed page similar to the template-npcbox i showed you above, so that the "descriptively-filled-in" one can be brief and less visually cluttered.

...

I know that Seth and someone were changing around the code of the ACTUAL Create_new_item form and perhaps what it does or how it does it... I don't know anything about that, except that I had a bit of trouble with the javascript version.

And as far as editing that page.... I wouldn't touch it with a ten foot pole, I'd break it in a nanosecond. ! :) -Adelas (talk) 13:04, 17 October 2011 (EDT)

Seth's Comments

...because I have no idea now where to add thoughts "in-line." Please forgive me for my parenthetical-laced writing style, heheh.

- Regarding the , they are most likely a holdover from when that sort of information was actually copied into the page, before the boilerplates were developed and the preload pages cleaned out. You can still see them appearing in many old quest pages (see this old revision of a quest, for example), and cleaning them out is just one of the minor maintenance things that often need doing around here.

- Let me clarify here (my understanding of) "who's on first" with regards to boilerplates, templates, preloads, documentation, and the like, to borrow Magill's phrasing:

Boilerplates: These pages should summarize how to style/format a full page, including its component template(s). Thus a boilerplate for items describes the item template (currently {{Item Tooltip}}) and all the contingent descriptions, etc. That's what Adelas seems to be accomplishing here (as an update to the current Boilerplate:Item. Each "Create new..." (both the current version - which should be unbroken now - and my planned ~~User:Sethladan/Sandbox|revision~~) tool should load a boilerplate above the edit box when new pages are created. Other than that, it should be the last word/ultimate standard for correcting formatting for relevant pages.
Preloads: Unlike boilerplates, these are bound to specific templates and might be analogous to the "clean copy" section on some boilerplates. These are what's loaded into the edit box when you create a new page using the tools. Not every template will have a /Preload, but the preloads that do exist should contain blank entries for each of the parameters used by that template without documentation of any sort (to avoid the issue mentioned in my first paragraph about comments).
Template Documentation: (What you see on Template:Npcbox, for example) Like preloads, these are bound to templates and explain how to use the parameters for that template but not any other extra information that would accompany the template. As EoD and I have bemoaned, documentation is sorely lacking for many templates around here, so it's a work in progress. That said, template documentation can/should parallel the "explained" section of a boilerplate - compare the top and bottom sections of Boilerplate:Skill for instance. Ideally, template documentation should be located on a /doc subpage of the Template and not otherwise loaded anywhere else but that Template page. (Template:Skill/doc - although this should be a lowercase "doc" - appears on Template:Skill and nowhere else.) The level of detail in a documentation page depends heavily on the template - {{Npcbox}} has about 20 parameters while {{Skill}} has over 80.
Template Pages: Ideally, these should contain only the code for a template and then transclude in the respective /doc page. This is the code that's called when you enter {{Skill ... or {{Item Tooltip... or similar curly brace bits. When viewing the page, the code will be invisible and readers should just see the documentation that's transcluded in. Again, work in progress, not all pages up to standard.

Whew. I don't know how much of that is already common knowledge, so please forgive me if I went overboard with the explanation.

- Moving on to my plans for Create new item/~~User:Sethladan/Sandbox~~: As I think Magill mentioned above, I'm hoping to be able to consolidate the various "Create new..." tools into one page. This would still have the familiar text entry box and "Create New Page" button, but would add a drop-down selection list to choose from, say, "quest," "item," "npc," etc., and would then feed you the correct boilerplate and preload once you hit the create button. Thinking about it, I wonder if this would be more useful or less. I can certainly document the heck out of it on the code side to make it easy to maintain, but I don't want to introduce unnecessary complications if selecting the type of page from a list makes things more ambiguous(?). Feedback?

(for the record, Create new item should not be any different now than it has been for months/years. I made a mistake the other day that caused it to use the code for my sandbox version, but this should be fixed. Thanks Adelas for pointing out the bug.)

- Regarding the discussion about "basic" parameter definitions versus more verbose, in-depth, "plain text" explanations, I think Adelas' thought makes a lot of sense: The Boilerplate can have a brief one-liner identifying what should go into each parameter, as long as there's a link (probably to the Template page that shows full documentation) for more detailed information.

Along the same vein, it makes me wonder if we need the "clean copy" to show up when creating a new page (I would say we definitely need it on the boilerplate either way). Since the edit box is preloaded with exactly that clean copy, does having the extra code block above the edit box take up space without adding information?

- There's obviously a lot of thought going into this discussion, and I'm not sure if I hit on everything or missed an important point. Hopefully these rambling comments help somewhat. :) Sethladan 15:08, 17 October 2011 (EDT)

Addendum: I am overall very pleased with how the sandbox version of this boilerplate looks now and am looking forward to seeing it refined to what'll actually help people create items! Sethladan 15:20, 17 October 2011 (EDT)

Look at your man, now back to me

YESSSSSSSSSSSSSS that is exactly what I didn't know. I'm going to say it back to you so that I'm 100% sure I understood it correctly.

The Template is what makes the page work. It's the actual code that lives in the item page, that USES the parameters we enter.

Seth sez: 100% correct!

The Boilerplate is a table that we use for entering the parameters that the template uses. It exists as a filled-in version and a blank/clean version. A given category (item, npc, etc) may have add-on boilerplates that help regulate information that isn't part of the TEMPLATE boilerplate for that category; on my sandbox page, an example of an add-on boilerplate is the part about Drops (ie what the item drops from). (is there a better name for these "add-on boilerplates"?)

Seth sez: In my mind, the boilerplate is the entire page (Boilerplate:Item, Boilerplate:Skill, etc.). It contains subsections for dealing with the template's parameters and for "Additional Information" sections.

The Preload is a form that automatically creates another page, displaying the filled-in boilerplate as the initial preview, and inserting the clean boilerplate into the edit box for us. It also displays clean versions of the add-on boilerplates so that they can be easily copy+pasted into the edit box when relevant.

Seth sez: What you describe here is what the "Create new item" tool does. The preload (take a look at Template:Item Tooltip/Preload and hit edit) is just an empty template call (like the "clean copy" of the boilerplate) that doesn't do anything on its own. The "create new item" tool just grabs whatever's in that file and throws it into the edit box.

The Template Documentation explains every teensy little detail of how to fill in the boilerplate. It shows the filled-in boilerplate in brief format PLUS a nice long detailed list in paragraph format.

Seth sez: Sooort of. If you consider my comment about your understanding of "boilerplate," the template documentation explains only the template, but not the "Additional Information"/"add-on boilerplates." That aside, the formatting isn't standard yet, but you have the general gist.

Let me know if that is exactly correct or if my understanding still needs a little tweaking.

Is there a template documentation for the item template, then? where is it?

Seth sez: I think I answered this in IRC, but it may have gotten lost in the chatter: Template:Item Tooltip displays what we have in place as far as documentation (the documentation itself lives on Template:Item Tooltip/doc) for that template. It's likely significantly out of date, but this may help answer some questions about which parameters do what. You might also browse the discussion page to see some conversation about parameters that have been added over the years.

Also, feel free to add data in the empty lines in this sandbox. Or at least comment here letting me know what they're supposed to be.

-Adelas (talk) 17:30, 17 October 2011 (EDT)

Of all the templates to dive into working with, you sure picked one of the more complicated/involved/contentious ones, heh. If you can "get" Items, you can make it anywhere! Sethladan 21:24, 17 October 2011 (EDT)

Having lots of section headers feels weird to me, so I can't help but continue in here, sorry. :-P Added some additional descriptors to the sandbox page, and thought I would point out that - at sometime in the not-so-distant future - we're hoping to roll out more "narrowed-down" templates specific to weapons, armour, potions, etc. This should help cut down on the obscene amount of parameters needed in this monolithic template and make things a little more manageable for people who haven't spent a year or more buried to their noses in the morass of coding that is Template:Item Tooltip. Sethladan 21:54, 17 October 2011 (EDT)

Thanks :) I think I've got it now. So.... how not-so-distant are we talking about here? Adelas (talk) 23:21, 19 October 2011 (EDT)

But i LIKE lots of topics.

So, I semi-randomly spaced-in some of the lines so that it visually breaks it up a bit. What do you think about this change?

Theft -- I Admit

I updated the Boilerplate:Item with comments for each variable, stolen from this article with some formatting and editing. For example, "blank or" if blank is an option, next possible value, finally examples if any. short and crisp I hope. Feel free to edit, complement, and rectify. Bur remember that it is used by Create_new_item and maybe more. Now I must rush off for a while. -- Zimoon 12:53, 22 October 2011 (EDT)

Fancy! I feel all important and contribute-y now :)

Would it be okay to also update the boilerplate:item with the "add-ons" section, especially the updated samples? -Adelas (talk) 21:41, 22 October 2011 (EDT)

Seems Sethladan did all of that, great job. There are still some question marks, some parameters unknown what they do. Trial and error is a way forward I guess, want to help with that, "all important and contribute-y (k)now"? ;) -- Zimoon 05:46, 23 October 2011 (EDT)