Author Topic: Wiki Formatting (Read 3656 times)

Synric · « **on:** July 14, 2016, 05:44:25 pm »

Hey everyone,

As some of you may have noticed, over the last few days I've kinda taken it upon myself to reformat the pages on the wiki. I'm not making any content deletions (for the most part, more on that later), I'm simply changing the presentation of the pages to be more standardized. As of writing this I am around 100 out of 427 DBC pages in.

Obviously I am not in sole control of the wiki, and a lot of people contribute to it. Therefor I'm writing this post to try and explain my thoughts behind my changes and, more importantly, to get feedback about what I could do better, other users thoughts, and anything else you may have to say about the wiki.

Tables of Contents

I've been adding a Table of Contents to each page in the DB section. I know this may seem superfluous on pages with one entry, but for most pages, to me at least, it's about quick and easy navigation, and for the pages with one entry it's about standardization and presentation.

DBC Information

Directly under the TOC I like to include any short information that would relate to the DBC regardless of the version. This is information such as when it was added or removed, and a short explanation of the function of the DBC if necessary.

Version Sections

One of my major problems with the wiki is the randomness of a specific builds information within a page. I've begun to rearrange into a new setup. It goes something like this: Expansion (Oldest first) - Build - Table/Struct. Specifically formatted as follows

==Version==
Version number and build number, i.e., 3.3.5.12340

===Type of information===
Depending on who wrote it it's either ===Struct=== or ===Table===. Sometimes we have both.

Addendum: On this note, this will probably be the most controversial statement to some people in this thread: I prefer both. The wiki, in my opinion, should not be able helping one type of person versus another. Programmers would prefer it in struct form, content developers probably prefer it in table form. I prefer to have both types of information, it takes nothing away from the page. I'm not a programmer, I'm a content developer, and it helps me far more to have the table for quick referencing. On the flip side, the guy who writes the tools my server uses is able to easily copy/paste the struct. Everyone has their way and need of presenting information. I say let the users decide how they need it, it really isn't about us.

Extraneous Information

I try to keep extraneous information at the bottom of the page. This type of information includes any information that explains the information contained above. Usually this is information like Flags and what they do. I try to separate them based on version, usually by placing some sort of stop notice between expansions. Whenever something is added that takes up a value in a previous list (for example, in Wrath only values 1-25 work, then in Cata add 26-30, but also go and add value #3) simply note it for that value.

Other Information

Schlumpf prefers DBC information added in a structure style, I add information in Table form. Each one serves a purpose. Feel free to add either, only Schlumpf will judge

This post is for discussion about my changes, your ideas, things we can do in the future, and anything about these changes. Thank you for reading.

Edit: Removed expansion headings. Back to just by version

schlumpf · « **Reply #1 on:** July 14, 2016, 06:29:12 pm »

Please use __FORCETOC__ instead of __TOC__ to respect the wiki's layout and have it consistent across auto-toced and manually-toced pages.

There are templates for versioned sections, please use those. Especially for "extra information".

I don't like the multi-level versioning. Using the build as section only would be preferable to me. Also, I wouldn't add a section for struct and table.

I propose to drop build-specific categories and only use expansion based.

The goal should be to at one point automatically generate table and struct from the same description and compress descriptions as much as possible with conditionals so that information (comments, types, value ranges, …) are not duplicated and more important don't divert. This was the case a lot for M2 and M2/WotLK and is the case a lot of times on DB/ pages with multiple versions.

Synric · « **Reply #2 on:** July 14, 2016, 06:59:10 pm »

1) Must have switched off __FORCETOC__ at some point. My bad.
2) Thanks for the note on the version boxes. I'll go ahead and start using those
3) I can change it up if anyone else has a problem with the expansion level heading. As far as struct/table labels I propose 3 options, it's up to yall
- Keep them as is
- Keep them, but hide from the ToC (I dunno why we'd do this, but hell its an option)
- Remove them. Up to yall, I'm cool with whatever.
As far as repeating comments I don't really see the harm in the tables. Comments don't create new lines therefor not using up more space, and would alleviate the need to jump around with the definitions. If a comment needs to take up subsantial space it really should be in the extra information sections, in my opinion.
4) I can see why, but I can also see why not. It's kinda nice in my opinion to be able to search by version... I guess I don't really care either way
5) No comment. Don't really follow what you're saying.

Edit: After looking at how a few look with and without the expansion headers, I'm just gonna go ahead and remove those.

Amaroth · « **Reply #3 on:** July 14, 2016, 07:29:34 pm »

I wanted to do something similiar on my own, but I'm glad someone else, apparently more skilled than me started doing so instead ^^. Great to hear that you are working on this.

Gamh · « **Reply #4 on:** July 15, 2016, 04:52:49 pm »

It's very nice of you to take the time to do this and discuss it!

Version Sections: agreed with Schlumpf, keep it simple and just precise the build it was taken from, or the expansion if we don't have that information. We should also avoid duplicate information with table + struct and stick with one. I tend to think structs just give the best layout for information (like int types give you explicit boundaries). If some people have trouble with reading structs, it's possible to write a short guide to the types commonly used in structs.

Categories: same, drop the build here, not useful enough to care and in some cases we aren't sure of the build anyway.

Ascathos · « **Reply #5 on:** July 17, 2016, 03:03:02 pm »

DBC Proposal

Idea: Split DBCs for readability

[paragraph:nhohd9b9]How to ?

Instead of having the scheme as following:[/paragraph:nhohd9b9]

Quote

Title
_____
Description
[Index]

Table description according to version
______
[Description]

Structs according to version
______
[struct]Struct[/struct]

[paragraph:nhohd9b9]I propose the following:[/paragraph:nhohd9b9]

Quote

Title
_____
Description
[Index]

Existing variables that can occur in this
______
[Variables explained, subsectioned in versions and or additions by addon]

Structs according to version
______
[struct]Struct[/struct]

[paragraph:nhohd9b9]Why ?
This increases readability a lot. It improves looking up how certain tables works and also improves documentation.[/paragraph:nhohd9b9]

As displayed in the following pictures:
[attachment=1:nhohd9b9]Right now.jpg[/attachment:nhohd9b9]

To the following:
[attachment=0:nhohd9b9]Proposal.jpg[/attachment:nhohd9b9]

Code: [Select]

==Variables==
{| style="background:#FCFCFC; color:black"}
|-
!width="180" | Name
!width="80" | Type
!width="40" | Addon
!width="250"| Description
|- style="background:#E0E0E0;"
| ID || Integer || {{Template:Sandbox/VersionRange|min_expansionlevel=1}} || Interal identifier 
|- 
| Duration ||Integer || {{Template:Sandbox/VersionRange|min_expansionlevel=1}}   || Base Duration
|- style="background:#E0E0E0;"
| Dur. per Level || Integer || {{Template:Sandbox/VersionRange|min_expansionlevel=1}} || Duration Increase per Level 
|- 
| MaxDuration || Integer || {{Template:Sandbox/VersionRange|min_expansionlevel=1}} || Max Duration for this entry
|}


==Structs==

===0.5.3.3368, 4.0.3.13329, 6.0.1.18179===
 struct SpellDurationRec {
   uint32_t m_ID;
   uint32_t m_duration;
   uint32_t m_durationPerLevel;
   uint32_t m_maxDuration;
 };

Synric · « **Reply #6 on:** July 18, 2016, 07:10:34 am »

My plan had been to do this this previous weekend, but RL got the best of me. Eight days from now I'll have a bit of time to myself, and I'll update the wiki.

Problem with the variable idea: We keep the information presented in order. Blizzard does not. They sometimes randomize certain DBC columns from xpac to xpac... Any ideas to get around that?

Also, the columns in a dbc can change patch to patch. Doesnt happen often but for example theres a DBC who had a column added between 3.0.2 and 3.3.5. So, at least we'd need to add patch as well as expansion.

Ascathos · « **Reply #7 on:** July 18, 2016, 08:39:05 pm »

Could add versions if we are certain about things. Also, sometimes it would make sense to simply have them referred to. If a meaning changed throughout a few versions, that would also be covered

Example

Name Integer Addon Version Description
__________________________________
Duration Integer < Wotlk 12100 "Base Duration for spells"
Duration Integer =>Wotlk 12340 "Base Duration for everything, including life time"

Soemthing along these lines.

Synric · « **Reply #8 on:** July 18, 2016, 08:54:36 pm »

Thats rare, but it does happen. (See: spellpower.db2. Originally contained manacost, turned into PowerCost basically).

Still though, how do we handle the changing columns? For example (I dont have a DBC thats done this pulled up, but it does happen), in one patch the columns could be ordered like

ID
SpellID
Cost
Powertype
etc.

and then it gets re-ordered like

Cost, PowerType, SpellID, ID

How do we handle re-orgranization between patches?

Also, how do you propose handling when a column is removed? Like spell.dbc goes from a max of 315 columns to 8. I think theres just a bit too much changing to use 1 table on the page.

Ascathos · « **Reply #9 on:** July 18, 2016, 08:58:32 pm »

Code: [Select]

===0.5.3.3368===
 struct SpellDurationRec {
   uint32_t m_ID;
   uint32_t m_duration;
   uint32_t m_durationPerLevel;
   uint32_t m_maxDuration;
 };

Code: [Select]

===4.0.3.13329===
 struct SpellDurationRec {
   uint32_t m_ID;
   uint32_t m_someRandomStuff;
   uint32_t m_duration;
   uint32_t m_durationPerLevel;
   uint32_t m_maxDuration;
 };

Code: [Select]

===4.0.3.13331===
 struct SpellDurationRec {
   uint32_t m_maxDuration;
   uint32_t m_ID;
   uint32_t m_duration;
   uint32_t m_durationPerLevel;
   uint32_t m_someRandomStuff;
   uint32_t m_somethingElse;
 };

Something like this I could imagine.

Synric · « **Reply #10 on:** July 18, 2016, 09:11:43 pm »

Well if we do that are we not just in the same place we currently are?

Ascathos · « **Reply #11 on:** July 18, 2016, 09:13:53 pm »

The table overview ? We do. However, it would differ how we explain variables.

schlumpf · « **Reply #12 on:** July 18, 2016, 10:20:25 pm »

The one-big-table approach will suck if we have a lot of unknowns, which we often have.

Synric · « **Reply #13 on:** July 19, 2016, 05:28:57 pm »

Thanks for the suggestion Ascathos, it's a good idea in theory but I don't think I'm gonna go with it. I just have my doubts about it being the most effective way of displaying the information. We're just gonna continue with version-based tables for now.

On a related note, I'm gonna try and work through all the tables sometime next week, so if you have anything you'd like to see done you have until Tuesday to explain it if you want me to do it when I do the rest of this.

schlumpf · « **Reply #14 on:** July 19, 2016, 09:27:41 pm »

My goal would be to verify structures for an as big as possible range, annotating which versions it was verified with, all with the same struct, rather than having the same table multiple times. Other than that, we should somehow change to some meta format based on templates so that we can avoid having duplicate descriptions and thus diverting ones.

Menu