Information Presentation and Organization

Find a handful of guides and walkthroughs here!
User avatar
ryunp
Lava Lord
96 | 57
Great Popularity Badge
Has a thread with over 50.000 views
Common Love Badge
Earned over 20 cookies
Common Guide Badge
Created a complete character guide
Great Contribution Badge
Is an active collaborator / developer
This document explains and provides example code for information presentation and organization strategies using BBCode features.

Complexity can only be conquered through composition. Reducing large ideas into smaller components is critical for comprehension, and easy navigation of these components is just as important. Obtaining both of these properties makes large information sets magnitudes easier to traverse and digest.

The BBCode FAQ shows instructions for linking to external resources with the url tag. However there is no mention of linking to locations on the same page. I used this technique in most of my own posts (heavily in Crafting Compendium) to keep information organized and sections directly linkable.
New Crafting Compendium for 1.5 when?


Table of Contents
1 - General Presentation
2 - Document Structure
3 - Final Comments




Document Presentation


Section Contents
1.1 - Header
1.2 - Inter-Page Linking
1.3 - Font-Awesome
1.4 - Links + Font Awesome
1.5 - BBCode & Newlines


1.1 - Headers


Header tags in HTML help give structural meaning to various sections of the document. The forum code automatically applies styling to h# tags. While not immediately obvious: this is a huge bonus for post authors and the community. Standard styling promotes universal familiarity, readers will have a much easier time identifying and navigating through posts regardless of the content topic. Because of this, it is wise to use h# tags as section titles instead of manual text styling (large size + bold, color, etc).

HTML natively defines 6 Header elements: <h1>-<h6>. Here is a quick test to show how these BBCode heading tags get translated:

BBCode

Code: Select all

---------------
[h1]h1 Test[/h1]
[h2]h2 Test[/h2]
[h3]h3 Test[/h3]
[h4]h4 Test[/h4]
[h5]h5 Test[/h5]
[h6]h6 Test[/h6]
---------------

HTML Output

---------------
[h1]h1 Test[/h1]

h2 Test


h3 Test


h4 Test

[h5]h5 Test[/h5]
[h6]h6 Test[/h6]
---------------

Due to technical limitations, only h2 - h4 get translated into HTML. This limits section hierarchies (categorical depths) with predefined heading elements to only three tiers. A quick summary:

Code: Select all

BBCode Tags         HTML Output         Usable?    Underline?
----------------    ----------------    -------    ----------
[h1]h1 Test[/h1]    [h1]h1 Test[/h1]    No         -
[h2]h2 Test[/h2]    <h3>H2 TEST</h3>    Yes        Yes
[h3]h3 Test[/h3]    <h4>h3 Test</h4>    Yes        No
[h4]h4 Test[/h4]    <h5>H4 TEST</h5>    Yes        No
[h5]h5 Test[/h5]    [h5]h5 Test[/h5]    No         -
[h6]h6 Test[/h6]    [h6]h6 Test[/h6]    No         -
► Output Inconsistency


1.2 - Inter-Page Linking


Browsers can follow links that target the current page, scrolling the window to a specific location and adding a hashtag suffix to the URL: website.com/page#inter-page-link. This also adds a location history record into the browser (for Back/Forward buttons)

These inter-page links allow the reader to acquire links to specific sections of the page. These links exist in the global page scope, which means they will work between multiple posts, great for situations where reserved posts are required!

Traditional HTML uses anchor tags, but BBCode uses navlink and navtarget to setup this inter-page linking. A set of opening and closing Navlink tags will create a clickable link to a specified target. An example navlink:


To Header

Code: Select all

[navtarget]inter-link[/navtarget]
[h3]1.2 - Inter-Page Linking[/h3]

[navlink=inter-link]To Header[/navlink]



1.3 - Font-Awesome


This forum has Font Awesome v4.5.0 installed. Icons can be included by enclosing an icon name within an opening and closing [fa] tags.

There are a wide variety of icons for nearly any situation (Copy/Paste fails; find the icon fa- id below by Right-Clicking it, and select "Inspect"):
    Quantification: / / /
    Narrative Aid:
    Selections:
    Navigation:
For example, a discussion icon () could explicitly mark information that is subject to opinion, welcome to community debate, etc.

Font-Awesome Cheatsheet shows all available icons for v4.7.0. While looking through the list, any icons marked with a number above 4.5 are not available (version dependency shows up to the right of the name). The cheatsheet page prefixes icons with fa-, do not include this prefix in the BBCode tag:




Code: Select all

Cheatsheet                      phpBB Post          Usable?
-----------------------------   ----------------    -------
fa-fire [&#xf06d;]              [fa]fire[/fa]       Yes
fa-firefox [&#xf269;]     4.4   [fa]firefox[/fa]    Yes
fa-gitlab [&#xf296;]      4.6   [fa]gitlab[/fa]     No
fa-telegram [&#xf2c6;]    4.7   [fa]telegram[/fa]   No



1.4 - Links + Font Awesome


Since the navlink tag encloses text, Font Awesome icons can be used as the text for inter-page links or external links. These sweet graphics not only add style points; they reduce page clutter and help provide language-independent navigation elements:


Heading

Code: Select all

[navtarget]link-fa-ex[/navtarget]
[h2]Heading [navlink=link-fa-ex][fa]link[/fa][/navlink] [navlink=fa-links][fa]arrow-up[/fa][/navlink] [url=https://en.wikipedia.org/wiki/Font_Awesome][fa]wikipedia-w[/fa][/url][/h2]



1.5 - BBCode & Newlines


BBCode can be very picky about 'whitespace' characters, specifically newline characters. When using most of the BBCode tags, like align, hr, and code, extra HTML <br> tags are automatically added after the elements. Anytime Enter is used in the editor, an invisible newline character is added, which ultimately gets converted to <br>.

This means two HTML <br> get inserted after most BBCode tags. Extra text gaps can be extremely frustrating, and may seem potentially unfixable. The good news is that these formatting issues can be resolved with some unintuitive BBCode formatting.

The hr tag is helpful for grouping/separating information and exposes this issue more glaringly than other tags. Below is a progressive sequence of four examples (A - D, with three sections each) attempting to remove the gaps between various BBCode tags:

A) BBCode

Code: Select all

----------------------------------------
Line 1
[navtarget]test[/navtarget]
[hr][/hr]
Line 2
[hr][/hr]
[align=center]Line 3[/align]
----------------------------------------

A) HTML Output

----------------------------------------
Line 1



Line 2


Line 3
----------------------------------------

A) Conclusion

Garbage. Well, we now understand why: so f*** you too, HTML! The extra gaps can be removed by removing the newlines between some of the BBCode tags...

==========

B) BBCode

Code: Select all

----------------------------------------
Line 1
[navtarget]test[/navtarget][hr][/hr]
Line 2
[hr][/hr][align=center]Line 3[/align]
----------------------------------------

B) HTML Output

----------------------------------------
Line 1


Line 2

Line 3
----------------------------------------

B) Conclusion

The gap between navtarget and hr was fixed, but clearly there are other newline issues...

==========

C) BBCode

Code: Select all

----------------------------------------
Line 1
[navtarget]test[/navtarget][hr][/hr]Line 2[hr][/hr][align=center]Line 3[/align]
----------------------------------------

C) HTML Output

----------------------------------------
Line 1

Line 2
Line 3
----------------------------------------

C) Conclusion

Yes! Wait; there is still a gap between Line 3 and the last set of dashes. ANYTHING after a BBCode tag is going on the same line...

==========

D) BBCode

Code: Select all

----------------------------------------
Line 1
[navtarget]test[/navtarget][hr][/hr]Line 2[hr][/hr][align=center]Line 3[/align]----------------------------------------

D) HTML Output

----------------------------------------
Line 1

Line 2
Line 3----------------------------------------

D) Conclusion

Seriously. This is nuts. Consider fixing all the minor formatting issues after the majority of content is written, as the 'fixed' BBCode text is far less comprehensible.



2 - Document Structure


Section Contents
2.1 - Categorization
2.2 - Navigation Structure
2.3 - Table of Contents
2.4 - Section Headings


2.1 - Categorization


Documents tend to form branching structures of categorized information. Most trivial documents don't warrant much structural planning and navigational aid. With instructional documents, this concept quickly becomes indispensable as the content expands.

Offering navigation throughout a document reduces time spent traversing content for both new and returning readers. The two types of document complexity discussed throughout this document are flat and nested categorical hierarchies:


Flat Hierarchy

Example Categorization:

Code: Select all

Document
├── Stats
├── Skills
├── Gear
├── Leveling
├── Ubers
├── Farming
└── Conclusion


Nested Hierarchy

Example Categorization:

Code: Select all

Document
├── Stats
├── Skills
│   ├── Support Tree
│   ├── Damage Tree
│   └── Reward Skills
├── Gear
│   ├── Early Game
│   ├── Mid Game
│   └── End Game
├── Leveling
│   ├── Early Game
│   ├── Mid Game
│   └── End Game
├── Ubers
├── Farming
└── Conclusion

Choosing how to nest various sections requires a bit of commonality analysis. As long as the category information remains consistent, there really is no wrong way to organize information. An alternative structure to the above:

Code: Select all

Document
├── Stats
├── Skills
├── Early Game
│   ├── Gear
│   ├── Leveling
│   └── Skills
├── Mid Game
│   ├── Gear
│   ├── Leveling
│   └── Skills
├── End Game
│   ├── Gear
│   ├── Leveling
│   └── Skills
├── Ubers
├── Farming
└── Conclusion


2.2 - Navigation Structure


The display of document structure tends to have two orientations: Horizontal and Vertical. Horizontal layouts are more compact and work well for simple section information, but lack flexibility for visual branching. Due to the density of text, they offer less space for auxiliary markers like numerical identifiers.


Horizontal Orientation


StatsSkillsGearLevelingUbersFarmingConclusion

Code: Select all

[navtarget]nav[/navtarget]
[align=center][navlink=stats]Stats[/navlink] • [navlink=skills]Skills[/navlink] • [navlink=gear]Gear[/navlink] • [navlink=leveling]Leveling[/navlink] • [navlink=ubers]Ubers[/navlink] • [navlink=farming]Farming[/navlink] • [navlink=conclusion]Conclusion[/navlink][/align]



Vertical Orientation


Stats
Skills
Gear
Leveling
Ubers
Farming
Conclusion

Code: Select all

[navlink=stats]Stats[/navlink]
[navlink=skills]Skills[/navlink]
[navlink=gear]Gear[/navlink]
[navlink=leveling]Leveling[/navlink]
[navlink=ubers]Ubers[/navlink]
[navlink=farming]Farming[/navlink]
[navlink=conclusion]Conclusion[/navlink]



Nested Vertical Orientation


1 - Stats
2 - Skills
3 - Early Game
4 - Mid Game
5 - End Game
6 - Ubers
7 - Farming
8 - Conclusion

Code: Select all

[navlink=stats]1 - Stats[/navlink]
[navlink=skills]2 - Skills[/navlink]
[navlink=early-game]3 - Early Game[/navlink]
[list]
[navlink=leveling]3.1 - Leveling[/navlink]
[navlink=skills]3.2 - Skills[/navlink]
[navlink=gear]3.3 - Gear[/navlink]
[/list]
[navlink=mid-game]4 - Mid Game[/navlink]
[list]
[navlink=leveling]4.1 - Leveling[/navlink]
[navlink=skills]4.2 - Skills[/navlink]
[navlink=gear]4.2 - Gear[/navlink]
[/list]
[navlink=end-game]5 - End Game[/navlink]
[list]
[navlink=leveling]5.1 - Leveling[/navlink]
[navlink=skills]5.2 - Skills[/navlink]
[navlink=gear]5.3 - Gear[/navlink]
[/list]
[navlink=ubers]6 - Ubers[/navlink]
[navlink=farming]7 - Farming[/navlink]
[navlink=conclusion]8 - Conclusion[/navlink]



2.3 - Table of Contents


A Table of Contents is always recommended for documents with more than a few categories. The choice between horizontal or vertical orientated elements depends on a few variables. Visual preference is a major factor. Keep in mind that highly nested category structures can be reduced to just one or two depths in the Table of Contents display. Prefixing numerical identifiers in the ToC and Headings can give readers easy reference markers while scrolling the page.

Layout and code examples can be seen in the previous Horizontal and Vertical Orientation sections.


2.4 - Section Headings


Adding navigation elements to the heading is crucial for external linking. These also allow quick movement around the document. A solid setup for headers is to use for parent category, and for self-reference. This strategy works well for any depth of section headings.


Flat Hierarchy

Category structures with one tier only require one level deep of header linking:

Code: Select all

Document      (Table of Contents)
├── Stats       (Link to Self and T.o.C.)
├── Skills      (Link to Self and T.o.C.)
├── Gear        (Link to Self and T.o.C.)
├── Leveling    ... etc ...
├── Ubers
├── Farming
└── Conclusion

Example headings:
Skills

Code: Select all

[navtarget]skills[/navtarget]
[h2]Skills [navlink=skills][fa]link[/fa][/navlink] [navlink=toc][fa]arrow-up[/fa][/navlink][/h2]

Gear

Code: Select all

[navtarget]gear[/navtarget]
[align=center][h2][navlink=toc][fa]arrow-up[/fa][/navlink] Gear [navlink=gear][fa]link[/fa][/navlink][/h2][/align]



Nested Hierarchy

Same concept as the Flat hierarchy. With each nested category depth, the parent links will point one depth above itself. This relative linking scheme helps keep consistency throughout the hierarchy tiers:

Code: Select all

Document            (Table of Contents)
├── Stats             (Link to Self and T.o.C.)
├── Skills            (Link to Self and T.o.C.)
├── Early Game        (Link to Self and T.o.C.)
│   ├── Leveling        (Link to Self and Early-Game )
│   ├── Skills          (Link to Self and Early-Game )
│   └── Gear            (Link to Self and Early-Game )
├── Mid Game          (Link to Self and T.o.C.)
│   ├── Leveling        (Link to Self and Mid-Game )
│   ├── Skills          (Link to Self and Mid-Game )
│   └── Gear            (Link to Self and Mid-Game )
├── End Game          ... etc ...
│   ├── Leveling
│   ├── Skills
│   └── Gear
├── Ubers
├── Farming
└── Conclusion

With large amounts of nested categories, an additional Section Contents may help orient readers. Much like the Table of Contents, choosing Horizontal or Vertical depends on multiple factors. Horizontal can look cleaner, especially without the need for numerical prefixes.

Example heading and sub-headings with Section Contents:

3 - Early Game

Section Contents
3.1 - Leveling
3.2 - Skills
3.3 - Gear


3.1 - Leveling
...

Code: Select all

[navtarget]early[/navtarget]
[h2]3 - Early Game [navlink=early][fa]link[/fa][/navlink] [navlink=toc][fa]arrow-up[/fa][/navlink][/h2]

[u]Section Contents[/u]
[navlink=early-lvl]3.1 - Leveling[/navlink]
[navlink=early-sk]3.2 - Skills[/navlink]
[navlink=early-gear]3.3 - Gear[/navlink]


[navtarget]early-lvl[/navtarget]
[h3]3.1 - Leveling [navlink=early-lvl][fa]link[/fa][/navlink] [navlink=early][fa]arrow-up[/fa][/navlink][/h3]
...


Early Game
Section Contents
Leveling
Skills
Gear


Leveling
...

Code: Select all

[navtarget]early[/navtarget]
[align=center][h2][navlink=toc][fa]arrow-up[/fa][/navlink]Early Game [navlink=early][fa]link[/fa][/navlink][/size][/align]
[align=center][u]Section Contents[/u]
[navlink=early-lvl]Leveling[/navlink]
[navlink=early-sk]Skills[/navlink]
[navlink=early-gear]Gear[/navlink][/align]

[navtarget]early-lvl[/navtarget]
[align=center][h3][navlink=early][fa]arrow-up[/fa][/navlink] Leveling [navlink=early-lvl][fa]link[/fa][/navlink][/h3]
...[/align]


Early Game
LevelingSkillsGear

Leveling
...

Code: Select all

[navtarget]early[/navtarget]
[align=center][h2][navlink=toc][fa]arrow-up[/fa][/navlink]Early Game [navlink=early][fa]link[/fa][/navlink][/size][/align]
[align=center][navlink=early-lvl]Leveling[/navlink] • [navlink=early-sk]Skills[/navlink] • [navlink=early-gear]Gear[/navlink][/align]

[navtarget]early-lvl[/navtarget]
[align=center][h3][navlink=early][fa]arrow-up[/fa][/navlink] Leveling [navlink=early-lvl][fa]link[/fa][/navlink][/h3]
...[/align]




3 - Final Comments


As this document evolves, constructive criticism is welcome.

Random Side-Note: The Crafting Compendiums navtarget identifiers are numbers (1-1-1). However, I would rather they be words describing the sections, but the Crafting Compendium is so large it ran out of room (59917/60000 characters). So the numbers were a compromise.

Contributions
Big thanks to those who contributed constructive criticism and suggestions:
Edited by ryunp 1 month.
FluxGenesis
Bone Archer
73 | 0
Common Supporter Badge
Donated 1 time
Sorry 4 bit OT, but...

ryunp wrote:New Crafting Compendium for 1.5 when?


SIGNED!! 8-)
User avatar
ryunp
Lava Lord
96 | 57
Great Popularity Badge
Has a thread with over 50.000 views
Common Love Badge
Earned over 20 cookies
Common Guide Badge
Created a complete character guide
Great Contribution Badge
Is an active collaborator / developer
Overhaul to the second major section. Added more BBCode examples.

The document may be getting a bit rough to digest with so many code blocks, but it's more of a technical reference source than a typical narrative-driven document.
User avatar
Taem
Polar Worm
1861 | 46
Common Posting Badge
Posted over 1.000 messages
Great Popularity Badge
Has a thread with over 50.000 views
Common Love Badge
Earned over 20 cookies
Common Supporter Badge
Donated 1 time
I really like this post a lot! Thanks for sharing! Did you explain how to make the horizontal bar you use beneath each header?
User avatar
ryunp
Lava Lord
96 | 57
Great Popularity Badge
Has a thread with over 50.000 views
Common Love Badge
Earned over 20 cookies
Common Guide Badge
Created a complete character guide
Great Contribution Badge
Is an active collaborator / developer
Taem wrote:Did you explain how to make the horizontal bar you use beneath each header?


I never did mentioned manually adding horizontal bars. Simply using hr tags will do the trick. There are some examples in the new '1.5 - BBCode & Newlines' section that use the hr tag. Also note that the horizontal bar is automatically added underneath h2 text, but not under h3 and h4 text! Updated '1-1 Headers' section to show the differences.

The new '1.5 - BBCode & Newlines' explains dealing with potentially frustrating unwanted gaps between text. The example section might be a bit confusing, but it hopefully offers a decent explanation of the root cause. Ensuring consistent formatting is generally the last step in a polished document, as smoothing out discrepancies usually whacks out the readability of the BBCode.

1.1 - Headers: updated code examples
1.5 - BBCode & Newlines: added section
AAlpha01
Vampiress
36 | 0
Common Supporter Badge
Donated 1 time
Is there a forum thread that shows all possible BBcode that is usable in MXL forum post? Wanted to post an image in a thread but it was way to big - a BBcode google search showed how to resize, but it apparently did not work on our forum.
User avatar
Marco
Team Member
1853 | 1152
Common Posting Badge
Posted over 1.000 messages
Legendary Popularity Badge
Has a thread with over 250.000 views
Legendary Love Badge
Earned over 500 cookies
Common Multiplayer Badge
Has won a multiplayer contest
Legendary Contribution Badge
Median XL Team Member
AAlpha01 wrote:Is there a forum thread that shows all possible BBcode that is usable in MXL forum post? Wanted to post an image in a thread but it was way to big - a BBcode google search showed how to resize, but it apparently did not work on our forum.


viewtopic.php?f=25&t=618

Those are obviously in addition to the ones from the posting menu. Short answer is there isn't resize support currently.
AAlpha01
Vampiress
36 | 0
Common Supporter Badge
Donated 1 time
Marco wrote:https://forum.median-xl.com/viewtopic.php?f=25&t=618

Those are obviously in addition to the ones from the posting menu. Short answer is there isn't resize support currently.


Well that answers my question - thanks!