Lack of interest Suggestions for making the BBCode help more friendly

[Dominion]

While translating the BBCode Help page I came up with some suggestions that would make it even more user friendly. Hopefully these changes would make BBCode more accessible to less technically minded forum users. (I'll omit tag brackets below to avoid BBCode confusion.)

1) Rewrite the titles and descriptions for goal-oriented presentation.

Currently each item lists the tags first, then says what you can do with them. This order is helpful to someone trying to understand text that's already marked up, but not so helpful to a BBCode newbie who knows what he wants to do but not how to do it. I'd suggest something like this:

Boldface, Italics, Underlining, and Strikethrough​

You can enclose characters with the B, I, U, and S tags to change their formatting.​

Of course the examples follow to clarify which tag does what. I would be happy to handle the rewrite of this page, if that would help ease the burden on the developers. (All that's needed is a rearrangement of language resources and an easy tweak to the BBCode Help CSS file.)

2) Reorganize the page so similar items are adjacent.

It seemed to me that certain tags would be easier to understand if they were near other tags that do similar things. For example, it would make sense to put the explanation of the ATTACH tag under that of the IMG tag, as they both offer ways of inserting image files in a post. Likewise, the PLAIN tag could be moved next to the CODE tag, as both can be used to reveal code.

3) Provide better examples for IMG, MEDIA, and ATTACH.

The example for the IMG tag is hardcoded to pull an avatar image out of the Xenforo file hierarchy. New BBCoders may find it hard to understand what the example is getting at. Would it be possible to provide a more realistic example that will look more like what the user wants to do? Maybe it could pull a nice little image from a folder close to the root of the xenforo.com domain, for instance.

The example for MEDIA is a dummy with no actual output. Would it be possible to replace it with an example that works? For example, it might be possible to create a lightweight Flash animated version of the XenForo logo and post it on YouTube.

ATTACH likewise has a dummy example with no output. Since this tag is created by the editor and included in the help page only for clarity, perhaps this doesn't need to be an actual working example; instead you could have the "output" column display thumbnail and full-size versions of an image stored in the XenForo file hierarchy.

Summary:

None of the above is very urgent. I'm merely suggesting possible changes that would improve user experience by helping folks to learn BBCode more quickly.

The changes in points 1 and 2 are easily accomplished, and I'd be happy to provide the labor.

The changes in point 3 involve more than a quick modification of language resources and code, and may be best left to the whim of individual forum admins who are prepared to mod a little and feel their users can benefit from better examples.

 

[Dominion]

Here's something else that could be added to the above suggestions:

4) Improve the explanation of the INDENT tag.

There are two problems with the explanation of the INDENT tag as it currently stands:

First, the explanation contains no reference to the optional INDENT=depth parameter that allows the user to specify how far the text is to be indented. This is not a huge problem, because the parameter can be omitted when entering the tag manually. If the user goes back and tries to edit the BBCode, however, he will find that this parameter has been added by the editor. Expanding the explanation to include this parameter will alert users to it from the start rather than force them to puzzle it out later.

Second, the explanation recommends nesting INDENT tags to increase the depth of indention. But the editor will try to combine nest INDENT tags, creating a single INDENT tag with a larger depth value. Since nesting can often be confusing to users without a programming background, it would probably be best to omit the nesting and focus on the depth parameter.

Generally speaking, if folks want to edit BBCode manually, they are probably ready to deal with the depth parameter. Anyone who would find it confusing will most likely prefer to use the WYSIWYG editor buttons instead.