Boards›Boards Feedback

Writing for the web & the Community Beta

RiotMontag·10/1/2013, 8:06:38 PM·9 votes·5,402 views

I want to talk to you guys about writing, specifically about Markdown. If you're familiar with Markdown, BBCode, Textile, WikiCode, or other methods of writing for the web, I want you to be a part of this discussion.

Our goal with the community beta is to make the best use of your time as a contributor and as a reader of content about League of Legends. Writing is core to that goal. We need to have a great platform for writing to have fruitful discussions that are worth reading. Only join in if you're OK with a wall of text: I write a lot, but I try to make every word count.

What is Markdown?

Markdown is a minimal syntax designed to make writing for the web easy-to-read and easy-to-write. If you write in block paragraphs and use stars for emphasis, you're already writing in Markdown. The result is that most people can read and write Markdown without a lot of upfront learning. I'll go into some syntax examples, but if you're interested in details, check out the official Markdown spec at Daring Fireball. That's also a slight tease of the syntax style, since we don't support in-line links at the moment. We might in the future, in which case this sentence won't make sense.

By the way, all this exposed Markdown is 100% on purpose. I just think it's beautiful.

Where I'm coming from

I'll put my cards on the table: I'm a huge Markdown fanboy.1 Virtually everything I write starts in Markdown, regardless of where it ends up: an email, a guide, an announcement, a presentation, whatever. Lots of other smart people have written about why they like Markdown, so I'll steal the list from Brett Terpstra's two-minute Markdown explanation. Brett captures my feelings exactly:

It’s easy: the syntax is so simple you can barely call it “syntax.” If you can use an emoticon, you can write Markdown.

It’s fast: the simple formatting saves a significant amount of time over hand-crafted HTML tags, and is often faster than using a word processor or WYSIWYG editor. It speeds up the workflows of writers of all ilk, from bloggers to novelists.   It’s clean: Markdown translates quickly to perfectly-formed HTML. No missing closing tags, no improperly nested tags, no blocks left without containers. You also get 100% less cruft than exporting HTML from Microsoft Word. There’s no styling inline, nothing that will otherwise break a site’s design or mess with the XSLT formatting for PDF output. In short, it’s foolproof.   It’s portable: your documents are cross-platform by nature. You can edit them in any text-capable application on any operating system. Transporting files requires no zipping or archiving, and the filesize is as small as it can possibly get.   It’s flexible: output your documents to a wide array of formats. Convert to HTML for posting on the web, rich text for sending emails or importing into a layout program for final arrangement or any number of other proprietary formats.   It fits any workflow: You can make Markdown work with any workflow. It can speed up just about any writing-related process with very little setup. It can also be scripted all to hell, if you want, because plain text is the most flexible of any format known to computer-kind.

So that's me. I <3 Markdown. I could talk your ear off about email, document, and presentation workflows, but for now, I want to talk with you guys just about writing for discussions on the web, and specifically contributing to discussions on Community Beta.

Markdown and BBCode

Markdown started small and has expanded a lot beyond its roots as a way to write human-writeable and human-readable words bound for HTML, especially in the realm of web-based discussion. Some notable sites that use Markdown for discussion are:

  • GitHub
  • reddit
  • Diaspora
  • Stack Overflow
  • OpenStreetMap
  • SourceForge

BBCode has also had a big presence in online discussions, especially around games. Markdown and BBCode are siblings in the world of web-writing: they're both trying to making writing for the web easier. However, they have very different approaches to that task.

BBCode was introduced in 1998 as a way of adding simple markup to message-board-style discussion. Where Markdown tries to keep its syntax minimal to optimize readability, BBCode isn't shy about its markup. It mimics HTML/XML in its use of tags to denote formatting, and as a result, both BBCode and HTML suffer from a similar problem: you have to really learn BBCode to both read and write it. The result can be difficult to parse, even with knowledge of the syntax.

You guys have all already absorbed that knowledge and you probably don't even remember doing it, so BBCode reads and writes really easily to you. But I'd challenge you that it's worth considering Markdown as a replacement. Let's get super geeky for a second and dive deep into an example to look at how Markdown differs from BBCode. First, here's some HTML.

http://imgur.com/9TEPxRb

Certainly readable, but there's lots of extraneous stuff. Each paragraph needs 7 characters just to exist as a separate entity. Both blockquotes and lists need opening and closing tags to indicate them, and lists are anything but natural to type out. Links are the worst. To type a link, you have to type 15 characters, not includuing the URL. Writing the above in BBCode is a lot easier, but you can still see remnants of HTML's influence:

http://imgur.com/ZeJ1PQU

Still readable, and certainly more readable than the HTML, so that's a plus. Syntax character count is also down across the board, but it's still pretty high. Creating the link now takes 12 characters instead of 15. Character count for lists is also down, but it still takes 3 for a single list item as well as open and closing [list] tags.

This is the same text in Markdown:

http://imgur.com/oWuRmbW

First-level heading is a single character with an optional closing character. (I use the closing character because I think it looks nicer.) The leading space is also optional. Italics and bold are 2 or 4 characters respectively, 3-5 characters shorter than BBCode. Lists and links are elegant and simple. A list is just a series of items that start with a dash and end with a carriage return, and you can use a star if you like that better: only two characters if you count the space. Links are easy and still highly readable: two sets of opening and closing brackets for a total of 4 characters, down from BBCode's 12. Counting only syntax markup for each example, Markdown requires 68% fewer characters to produce the same formatting as BBCode.

68% fewer characters.

In my opinion, Markdown clearly comes out ahead in readability and elegance.

Tradeoffs

You do lose some things switching to Markdown, but I'd argue that it's a net gain in favor of clarity. Many of you who weren't already familiar with Markdown were probably perplexed that a single line-return doesn't create a new line2 or that you don't have as much control over things like indentation, text alignment, etc.3 That's part of what I want to dig in with you guys.

With Markdown, increased clarity comes with trade-offs. For example, if you have a lot of items with single-line returns, Markdown forces you to consider what you're really trying to convey with your text and apply the right formatting for the job. Let's look at some examples:

  • If it's a list, it would be a ton easier to read if you formatted it as a bulletted list.
  • If it's poetry or a medium that has specific line-breaks, Markdown still has you covered: you can add two spaces at the end of a line to force a hard return. Looks good to the reader and isn't a lot of extra effort for the writer.
  • If you've got a bunch of paragraphs only separated by a single line return, I bet we can all agree it's hard to read a wall of text with no line breaks. Consider two line returns to give your audience a breather. Plus, you get the benefit of proper web-styling: we now know that you're using paragraphs, and we can style them appropriately.

All of these are slight inconveniences compared to BBCode that nets a ton of clarity for both writers and readers, in my opinion.

Riot-flavored Markdown

But some trade-offs may not be worth it, or maybe there are features that you guys absolutely need in your writing that we haven't provided yet, and that's what I'd really like to dig into with you guys. We want to figure out what Riot's flavor of Markdown is, and we need your help to do it. I've already used a bunch of Markdown and MultiMarkdown formatting, like inline- and reference-style links and footnotes respectively, that we don't support today. Maybe we should. Or maybe we should add tables. Or wiki-like links to champion or item stats. We can do a lot, but we can only set our priorities and make good decisions decisions based on your feedback. Remember our goal: to make the best use of your time as a contributor and as a reader of content about League of Legends. With every decision, we're always shooting for that star on the horizon.

So talk to me about your use of Markdown, coming from a world filled with BBCode. What do you love about it? Where are your frustrations? Where are Markdown's trade-offs unreasonable? What would you like to see? What do you absolutely need? This is the place to talk about it, so go ahead, post away.

Edit: Cleaned up a few reference-style links now that in-line linking is available.

Footnotes

  1. I mean, look at these footnotes. That's not even Markdown proper. It's MultiMarkdown, which is a user-created superset of Markdown. I know, I'm a lost cause. ↩

  2. We've implemented a strict interpretation of the original spec on Daring Fireball. Not everybody does it this way. GitHub, as an example, respects all carriage-returns as a <br /> tag in output. I've had lots of discussions with Krylhos about this. They get heated sometimes. Yes, heated discussions about carriage-returns. I direct your attention to the above footnote. ↩

  3. We haven't implemented all of Markdown yet, so there are some gaps. As an example, full Markdown allows HTML inside properly-formatted Markdown, and it'll interpret it as is, so a lot of these issues are very solveable in the standard Markdown spec. Naturally, we have some security concerns about allowing arbitrary HTML, but allowing some HTML is not totally off the table or figuring out other ways to get around it. MultiMarkdown adds Markdown syntax for tables, as an example. ↩

39 Comments

Pryotra10/2/2013, 2:34:23 AM5 votes

As a man who knew Html before ever being exposed to bbcode, bbcode was as natural as breathing. It really is not hard to pickup, and is really clear in how it will look. I for italicize, B for BOLD, U for underline which this board needs, s for strikethrough, * for bullets, quote to guote people, ect.

The main problem with learning markdown on your site is that I need a dictionary to do it, in the way of your formating guide. Bbcode allowed the less tech savy people to skip the learning process, which I feel would go a long way here. If you want your user to use something, make it clear, yet simple.[I] and [/I] around text clearly italicizes things, and it is easy to go back and add formatting where neccessary. I don't even technically need shift, where as if my keyboard doesn't have a number pad, I still need to hold shift or use... sticky keys. shudder

However, I have been experimenting with formatting as much as I can in posts. I must say, markdown is better for formatting on the go, but it lacks clarity. What is the difference between this and this? The first one used stars, the second underscores. What about this and this? First one used underscores, second one used stars.

Also
who am I quoting?
Quotes feel bad without a way to refer to the OP
and I shouldn't have to copy pasta, then format to quote someone, that just feels bad.

Also, do I really need a character between Quotes? What if I wanted to respond to a quote with another quote!

feels bad man.

And while we are on Quirks, what is the difference between

  • this
    and
  • this

Protip: The first uses {*}, while the second uses -

While I'm still at this _ guess how I did this? It isn't what you think! _ * I can do it with stars too! * * Bold isn't necessary I think._ _*

So without further ado, let me end the annoying formatting and get down to brass tacks:

  1. Formating needs to be clear on its purpose.
  2. Redundant ways to do the same thing need to be eliminated, other wise they fight each other.
  3. You need to implement more basic features, like underlining, strikethrough, and links
  4. One thing I hate is the reliance on imigur. Our current boards don't need this, why does this forum? What happens if their service goes down?
  5. User friendly is key. If you go back to do your edits to formatting, bbcode feels friendlier. I shouldn't need a manual to figure out how to bold some text.

I really hope that was entertaining, and that the post preview isn't lying to me. Hopefully this educated you.

JustMatt10/1/2013, 8:32:09 PM3 votes

I love Markdown because it's like writing a post in a more convenient version of HTML; since I'm in control of everything I type, I know that it won't be affected by things like copy/pasting over font formatting, weird snippets of code, or whatever else. It's a lot more convenient to type asterisks around something I want italicized instead of typing <i> and </i>. Also, the way links work (set a definition, be able to use it anywhere in the body) is awesome and saves a lot of time.

I'm a full-time writer, and instead of writing things in Word or in a CMS, I use Markdown because I can save what I write in .txt, which is universally accepted by a lot of programs, and doesn't insert weird code like .rtfs or .docs do. If anything, a lot of apps for tablets/phones will allow you to edit .txts, which in a pinch is great.

Basically, if you use Reddit, you've used Markdown, and if you do a lot of writing on the web, it's one of the most convenient systems to use in order to work quickly.

I use http://softwaremaniacs.org/playground/showdown-highlight/ in order to do most of my editing. You can put Markdown in the left pane and have a preview show up in the right. However, the thing I like most is the HTML export that you can access from the right drop-down. Format a post, copy/paste the HTML and you've got something that can go directly into a blog. The only thing is that it doesn't save documents, but if you're writing something in one sitting, this is aces.

ArchMagus Frost10/1/2013, 9:38:30 PM3 votes

Hi Montag! I just wanted to say that i pretty much have absolutely no experience with web writing. Im taking a couple of programming classes at college, but they dont deal with web writing or anything. So just from the stuff you've said i can honestly say that the simplest one for me to grasp is Markdown. It seems a lot simpler to format and such, but to me, the most important thing is that anybody with no experience with code whatsoever will be able to understand the concepts behind it. it could be as simple as skimming down your discussion here and getting a slight understanding of how to format their page. But the fact is that its relatively simple.

I have been playing league of legends since JarvanIV was released in S1 and ive never really been involved in the community outside of the game so i feel like its about time for me to contribute something to the new community. I love what you an your coworkers are doing for us and id like to help out however i can. I would imagine that being able to add tables and graphs to a thread would be pretty awesome and Im sure that a lot of people would find that rather convenient. Im not sure if this is a thing yet, but i know on the regular forums ive seen threads with polls that people can vote on for different things ie. http://forums.na.leagueoflegends.com/board/showthread.php?p=24847697 maybe im just crawling outfrom under my rock here, but is that available for anybody to do? or would that be another thing to consider? Anyways, thats my input! Thanks for all the stuff you're doing for us!

ModCaptainMårvelous10/2/2013, 3:58:26 PM3 votes

Testing header system

( To me that comes up as pound sign, space, testing header system, space and pound sign. No special text here. Also, Imgur is broken on the forums for some reason. Not sure if everyone has this issue or it's just me.)

If I may provide the view of a writer in terms of content-based writing (As opposed to discussion-based writing), I'd love to share my thoughts on this:

Foremost, the fact that markdown uses less characters is EXTREMELY useful for writers. This beta used to have a severely limited character amount that writing a long story was impossible (This has since been updated from the measly 2k to a generous 16k character count). That being said, markdown using less characters for each designated format is very useful. I can definitely put more into writing than having to limit myself due to bold/italicized/etc.

I do have to say that it can be a bit difficult to grasp at a glance. As someone who has used BBC and forum-style formatting ( AKA [b][/b] for bold, [i][/i] for italics, etc), I do have some trouble adapting to the asterisk style that's here. For example:

Blah blah blah

That's Bold and italicized. Yet there's no sort of reference for that in the formatting guide. Sure it's "Well duh just add 3 on each side". But at the same time, ordering lists is EXTREMELY specific.

*list *List

See, to me that should be a list item. But it's not. I had to mess around before finally cut-copy-pasting into the text box to figure out that there needed to be a space, then an asterisk, then another space, THEN your list item. It'd also help to say that you have to make every single list it's own paragraph, or else you end up with something like this:

  • Look at me I am putting a list right under a paragraph.
  • Wait this isn't working oh no!

Part of that comes from not being able to put text DIRECTLY under a paragraph (Which I'd hope there is a fix for) but so far that's just a minor inconvenience to me.

Block quotes aren't so bad. Though I think it'd help to note that the block quote only ends after starting an entirely new paragraph without any > marks.

One thing I really want to stress again is changing the formatting guide to instead be a quick insert system where you can highlight large amounts of text and hit a button to insert bold text, italicized text, etc. It can be somewhat of a pain to go through and carefully set out where you want certain types of text but I forsee this being more of a problem with bulletin points and the like.

Overall this system does take some getting used to but isn't so bad. While I prefer the [b][/b] style of formatting because it's quicker for me, this isn't so hard to be used to. Though, as a closing note, I'd really like strike-through/underline/possibly highlight on the list of formats to be considered.

Thanks for reading this and sorry if I went over stuff you already covered but I missed and/or neglected to see.

ploki12210/1/2013, 9:45:40 PM2 votes

First of all, I do believe that markdown is lacking on this community. But that much is pretty much know and acknowledged by everyone, so we'll skip that part.

Next, I do believe that Markdown is a wonderful way of formatting text. It's concise, precise and clear (once used to it).

However, the problem I see with Markdown is the same that I see Riot fighting against in LoL : Barrier of entry. Basically, ask your father (or in case you're roughly 15 and under, your grandfather) to format his text using Markdown, and he will slap you in the face before facerolling the keyboard because there's no [B] and [I] buttons up top.

So, like most apps you listed, you would need to have a mouse-only WYSIWYG editor, in my opinion, possibly triggered by a button at the far left/right.

N.B. Please check your font for that emphasized I, it's even worse than a slash (I vs /).
N.B.2 Also, make sure that if you keep the exact same possibilities as last platform (vBuletin), you fix the small inconsistencies like [INDENT] messing up line breaks big time... Also, pass that one to vbulletin team when you'll have time if you can, I may forget about it once again...

Speedkat10/4/2013, 8:05:52 PM2 votes
  • 0 spaces before *
  • 1 space before *
  • 2 spaces before *
  • 3 spaces before * * 4 spaces before *

    • 5 spaces before *

    • 6 spaces before *

    • 7 spaces before *

    • 8 spaces before * * 9 spaces before *....is this double-space listing intentional?

    • 5 spaces before *

  • 0 spaces before *
  • 1 space before *
  • 2 spaces before *
  • 3 spaces before * * 4 spaces before *
    • 5 spaces before *
    • 6 spaces before *
    • 7 spaces before *
    • 8 spaces before *
  1. This list is ordered
  2. This has one space
  3. This has 2 spaces
  4. This uses 3 spaces
  5. Why is this acting this way
  6. Does the number I use even matter?
  7. I headed this item with "893"
  8. Headed by "45", is this intentional?

Lists don't make sense to me. I can't speak for anyone else, but I'd prefer that my formatting (# of spaces heading a list item) carried directly over to how it displayed rather than (it seems) the Markdown choosing that the first item is base-level and carrying on upward from there.

Zielmann10/1/2013, 9:25:38 PM2 votes

At the moment, my biggest problem with markdown, as implemented here, is the complete lack of clarity within the Formatting Guide itself for some of the items. Some are straightforward (bold/italics). But lists had me confounded to the point of anger when I first tried to use them. Having figured them out, I can say that it's not that bad. But all that frustration could have been curbed by setting up the formatting guide on the 'Basic' page the same as the 'Paragraph' page, where you indicate when {space} and {enter} are necessary.

I don't mind learning the new formatting at all. And I've already gotten pretty used to using the bit of markdown that you guys have on here. I can say that it definitely does flow better than having to type [i][/i] every time I want to italicize something, for example. And the various combinations of spaces and enters required to put lines of text where I want them are becoming second nature already. But you have to give us the resources to see exactly how to get the output we want the first few times we use it, so we can learn it. If not, we're left randomly hitting space and enter and hoping we hit the right combination to put things in the right place.

In terms of what features to add, there are a couple that come to mind.

  1. In-line links are practically a requirement for me. I like when a post comes out looking relatively clean and polished, especially if I've spent a fair amount of time putting it together. And nothing ruins that polish like having to see some long URL floating about with its random hash string of characters and such just interrupting the otherwise-clean landscape.

  2. Header text is something I would like to see. I may not use it much, but I'm sure the people writing stories and/or role-playing might appreciate having them available.

  3. I would love to see the wiki-style links as you mentioned. Not only would it make it feel more integrated to the site, but it's just a nice feature to have. I actually used to frequent a fan-made League chat application. The guy writing it eventually put in an entire database of champions and items that you could view from the client itself. Whenever you would type 'sivir' or 'zeal', the program detected that, and would automatically make it link to the champion or item info.

And now I have a slight annoyance with the enumerated lists (I assume it would exist with a bulleted list as well). When you have multiple paragraph-long items, everything kinda blobs together. One of two things would help: Either have a way to allow a space between list items (I tried, and each item turns into a number '1' in the list), or modify the text alignment so that the additional lines are further indented, so that the item number sits in a column by itself, rather than getting absorbed by the new lines of text.1

Though that may just be an indication that I should have just written those out as separate paragraphs anyhow...

Footnotes

  1. Actually, in the post, it is displayed how I want it to be. This seems to be a bug/inconsistency with the preview pane, then. See: http://puu.sh/4FdLP.png ↩

Kajika9110/1/2013, 9:26:57 PM2 votes

I really like the markdown fomratting style, easy and powerfull.

Also the Riot's preview makes things even easier and the guide is clear and simple.
So for me it's 100% better than bbcode and HTML.

I can't wait to get more markdown's option in this beta (dat ^ to add some humourist lines inside a post for example).

Tortferngatr10/3/2013, 5:17:17 AM1 votes

My personal issue with the format seems to be unclear results for when I stack different Markdown tags for when I want to do things like bold+italics or just...normal asterisks. While it's easier to type, it sometimes doesn't feel readable or...writable...when I'm trying to mix those.

I honestly question whether having to put 2 spaces to get an "Enter" is particularly readable for the poster. It feels annoying on Reddit (and trust me, I use the League subreddit a LOT,) and it feels (still) somewhat annoying here (although being able to see the markdown as it's edited helps here partially).

I think that, having no typographical design experience, having the ability to parse a special hybrid option between BBCode and Markdown sounds like a possible way to at least give some way to allow BBCode's reliability and maintain Markdown's flexibility.

For example

insert text here

would read as

insert text here

The approach is already used for in-comment champion pictures on the League subreddit.

Of course, it could be the product of staying up too late at night and trying to solve things when I should be asleep...

Delta Sniper10/1/2013, 8:32:23 PM1 votes

Wow, ur asking us if we want something before you force it on us?

brunoais1/15/2014, 9:32:56 AM1 votes

As it is now, how do I make a list using styled numbered sublists?

Things like (I tried to make without it formatting automatically):

1
    1.1
        1.1.1
        1.1.2
        1.1.3
    1.2
    1.3
    1.4
2
3
    3.1

etc...? When I try, I get this:

  1. Something. 1.1 something 2. 1.1.1 something extra.

It does not sound right

brunoais1/9/2014, 3:37:25 PM1 votes

As a web dev and as an active participant of phpBB dev since 2010, by working with the update of the BBCode parser and the addition of a WYSIWYG parser. I can say that Markdown and BBCode are cousins where one is not better than the other.

Markdown has many issues that the makers try to hide. Some of them I've been having in the PBE forums.
I won't mention the good side of Markdown because that has already been made by Montag. So it does not mean that I don't think it has good sides, I just don't want to repeat them.
Back to the main subject, here's some an examples of markdown's problems. I want to write an asterisk before and after the phrase:

simple, right?

Not really... There's a solution, though:

*simple,right?*

For that I was forced to use the HTML entity. I don't think that many knows the HTML entities. They are made using:

&#[insertNumberHere];

In the asterisk case, the code is 42 (sorry, I can't show you an example due to Markdown's limitations). This is not written anywhere and I was forced to stop and think for a while how could I display that character. It wasn't straight forward to understand that but I got it after making some experiences. You may search for it in one of my PBE posts.

That was problem No1. There's more!

BBCode is super easy for someone that knows HTML (specially in the HTML3.2 and HTML4 era), markdown... not so much... But then, most people don't know HTML and I have the selfish idea that most people who are comfortable with HTML are people who learn Markdown with ease... And most people have no clue what HTML is so... I'll let that slip as I agree...

With Markdown, it's not easy to tell **bold apart from ** italic when it is not well

Markdown is very limited in how much different things it allows

You can make the newline, paragrath, bold, italic, underlined, strikethrough, links, "sorta" citations (no identification of the source :( ) and not much more.
Just like wiki-like syntax, there's a very clear limit to where Markdown can survive. It can only hold until it turns into something way worse than BBCode where one starts to crave BBCode to come back.

TvTropes forums have a good example of this, IMO. The formatting options are a complete mess after the very simple bold, *italic *and underline.
BBCode has none of these issues and that's what I've been used to. Besides, there's a big tendency of making the BBCode tags with a single-word-well-described-functionality. Something that Markdown is powerless.

Markdown is about "what" content. BBCode is about "what and how" content

With markdown, you you have the power of telling what you are making. You can place the emphasis, you may give more strength to something by using bold, you may make a bullet list or a numbered list but then...
What if I want the list using roman letters? What if I want to use a different font for a small except of text? Can I increase the side of my text? I don't mean a title or something like that. For titles, there's already the "#"

My cope with Markdown

My experience with Markdown started with github. I was constantly checking my text to see if it was displaying right. Their option of "\n = <br>" helped me keeping myself sane with the discussions there.

I also make most of what @Pryotra states as my own. Lots of what he wrote is exactly the same as with me. At least, when I started with Markdown.

Markdown on PBE and me

With the LoL PBE forums I was introduced to a worse markdown... a markdown I was unable to use just by looking at it. My only save was the formatting guide that appears on the bottom right. I was able to keep glimpsing at it from time to time. I still hate that you tempered with the @href attribute! When I try to open it in a new tab instead, it opens the same page instead of the formatting guide. That was a huge cognitive failure for me.