# What makes a wiki suck?

• For reasons I want to build my own markdown based wiki (maybe scratching a mongodb itch... maybe). One that doesn't suck and that people want to use.

It's still very early doors in the development - it's .NET based and released under a GPL license. Couple of in-progress screenshots below.

What I would like to know from the community is : "What makes a wiki suck?"

• Well, Markdown sucks, but then so does everything else, so.

• I wouldn't want to use a wiki built on Markdown; it's too poorly defined and with too many variances in implementation. I'm familiar with MediaWiki syntax, and find it halfway decent most of the time; then again, if I want to use MediaWiki syntax, I'll use MediaWiki

<!-- Emoji'd by MobileEmoji 0.2.0-->

• Landing pages. I can enter a wiki from a search and find what I'm after, and if it's well organized find more of what I want, but if I search for the wiki itself, I always seem to be in a super generic page about how to edit rather than how to find information.

• I'd much rather use a markdown than a markup - I want the content writers and editors to be presentation agnostic (how realistic this is remains to be seen). Worst comes to worst the markdown components are well segmented and can be replaced - just can't see there's anything better.

• For reasons I want to build my own markdown based wiki

Ok...

One that doesn't suck and that people want to use.

But you already said it has Markdown, therefore what you seek to do is impossible.

• I'd much rather use a markdown than a markup

Don't let the name fool you: Markdown is still a markup language

<!-- Emoji'd by MobileEmoji 0.2.0-->

• What makes a wiki suck?

For me it's the 'wiki' part that seems to be a barrier to keep things organised. Too many editors with too little thought process. Either that or too many Jeffs that stifles the creativity of the too many editors.

• Ok I'm going to spend some time and actually answer this kind of. If this is too stream-of-consciousness, well, tough luck because I ain't editing it.

First of all, your question is meaningless without knowing who your intended user is. Basically, if you're making a 100% general purpose wiki, you're competing against Wikimedia, and their markup language is seriously like 4-5 times more powerful than Markdown so you've already lost on that front.

90% of Wikimedia's problems stem from its asshole stupid moron leadership. So obviously no technology can solve that. 10% stem from its fucking terrible usability and accessibility. You can't combat the 10% while staying within the bounds of Markdown. Unpossible.

(BTW, the biggest reason Wikipedia has usability problems is because their markup syntax, while powerful, is too fucking hard to learn. You're not solving that problem with Markdown; you're just trading ease-of-use for power-of-expression. The real solution is a solution we all knew years ago: JavaScript WYSIWYG GUIs, backed by a "fallback" markup language. You know, the kind we had all perfected in 2008. But of course, in the great and mighty field of computer science, the last thing you ever want to do is actually learn from past experience or advance the industry in any way whatsoever! Cry out your combined voices in the Silicon Valley cheer, "no forward progress! No forward progress!")

So let's take a look at products you could build and be successful at. Here's some ideas:

Look at what Sharepoint does, and basically replicate it. By this I mean, Sharepoint has different page types (the information you put into, say, a Gantt chart is very different than the information you put into a calendar which is very different than the information you put into a table-formatted-- so why just have one uber-generic page type to handle both cases? So take the Sharepoint idea of having different page types for different types of information and improve on it. Maybe you could design a "dashboard"-type page that allows the different content types to reflow like a Wikipedia page would allow, but without the hassle of having to format your Gantt chart in crazy-wiki-language.

Take a cue from Hypercard (or PowerPoint, which has a similar syntax), allow the user to make "template" (or "background", in Hypercard terminology) pages with placeholders for actual content. Materialized pages keep reference to the template they were materialized from, so changes to the template will change all those pages simultaneously.

Here's an idea. A lot of wikis are used for generating documentation of code. A lot of REST API code libraries can auto-generate descriptions of their endpoints. (Think: ASP.Net WebAPI "help" pages, Ruby on Rails "scaffold" pages, WSDL files, etc.) How about a wiki that lets you easily import this data for documentation purposes? How about one better, how about it monitors these various API references and tracks when new endpoints are added? I'm pretty sure there's no existing wiki software with that feature.

• One thing that always annoys me with wiki-s is that there is no good browsing capability. Sure, you can search the thing or follow hyperlinks between the pages, but... it never feels enough. I guess some kind of tags would help? Or a tree-like structure of categories?

Note that most of my experience is from various game wikis I keep open (eg. terraria crafting). Not sure if this is the problem with the way authors use the software or the software itself.

• EDIT: oh another thing I thought of but forgot to put in my post!!!!!

MongoDB's record size limit is 16 MB. That might be tight for a wiki page. Definitely tight if you wanna keep the revision history and current contents in the same DB document.

So you're either gonna wanna pick a new DB, or you'll be constantly working-around Mongo limits and it'll drive you mad.

• A good wiki has a tree-like structure of categories with a single root so you can go up and down... once you get started someplace.

• a tree-like structure of categories

But... it's there in almost every Wiki imaginable.

In general, I like Blakey's idea of template pages, and generally agree that ditching Markdown and just keeping a sane subset of HTML and maybe a WYSIWYG editor (though I hate those things personally) would probably be better.

Oh, and a somewhat-live preview - just don't go the Discourse way of having a JS port of your backend logic. I'd rather hit a "refresh" button which tells the server to render the snippet in question than amuse myself with inconsistencies between the "baked", "half-baked" and "totally baked" versions of the page.

• Or, in short, "look at Discourse. If it does something, don't do that".

• The general notion is markdown -> html fragment (unstyled) -> template (introduces classes) + site layout (introduces stylesheets) = site page html.

Live preview is a must, and front / back end parsers MUST match.

• Thanks for the headsup - had already planned on them being distinct, looks like a good choice.

• I like how you ignore my long well-thought-out (ok, just kidding, it was brain droppings) post and focus on the tiny one about a niggling little technical detail.

• But... it's there in almost every Wiki imaginable.

I'm not much of a wiki poweruser. Consider me a noob advocate in this thread.

If I couldn't find it and/or navigate easily on multiple wikis I've used, there's room for improvement there.

• If I couldn't find it and/or navigate easily on multiple wikis I've used, there's room for improvement there.

Indeed. I usually end up pointing google to that site to try to find something if a bit of wandering through the obvious links doesn't seem to be working.

I rarely try to navigate any wiki, other than from something piquing my curiosity as I'm reading. If I'm actively looking for something, it's coming from a search engine.

• Sorry - wasn't ignoring it - trying to take it all in

The main audience is for people that want to be able to compose structured and organised content without worrying unduly about syntax.

The templating approach is a definite requirement, I want as much of the presentation to be determined by the structure around the article than the article itself (having said that article stereotypes will come in handy).

Markdowns role is limited to the rendering of the article content to an article HTML fragment.

• Markdowns role is limited to the rendering of the article content to an article HTML fragment.

Markdown doesn't support a tenth of what HTML does.

• if you want to learn about poor wikis, try googling the name of a book series (not Harry Potter, something smaller like Dresden Files or [Anita Blake][1]) or a video game series with "wiki" on the end. Almost every fandom has at least one, and most of the smaller fandom wikis are terrible. That'll show you where you could automate or enhance discoverability of best practices.

• Personally I'd go with good old HTML for pretty much anything that needs a markup language today. But I guess it depends on the audience. Markdown is easy to use for simple documents but downright terrible if you try to make anything complex.

So my suggestion is: support both. Either as a site-wide setting, or a per-page option, or even per-section, I don't know. Just not both at the same time like Discourse's markup-soup.

Maybe a WYSIWYG editor, with an option to drop down to Markdown, or HTML? Maybe make it plugin based?

• Which is why I'd be using it... Simpler syntax, shorter learning curve, less complexity.

• Which is why I'd be using it...

Right; but you're wrong to do so.

Simpler syntax,

A WYSIWYG editor has no syntax.

shorter learning curve,

Everybody already knows how to use a WYSIWYG editor.

less complexity.

True; but a WYSIWYG editor has even less complexity while simultaneously having far more power.

If you go with Markdown, you're going to have the same Wikipedia problem where the only people who can tolerate/enjoy the process of editing an article are those annoying "well, actually..." dickweeds.

• True; but a WYSIWYG editor has even less complexity while simultaneously having far more power.

It's also true they're not a panacea; many WYSIWYGs are more like WYSISOWYGIYALs, especially when it comes to generating HTML from them.

<!-- Emoji'd by MobileEmoji 0.2.0-->

• It's also true they're not a panacea;

What!? You mean it's not a MIRACLE that will solve all problems everywhere? Say it ain't so, Joe!

many WYSIWYGs are more like WYSISOWYGIYALs, especially when it comes to generating HTML from them.

Mostly I'm still bitter than it's 2015 and we have worse text editing options than we did in 2008, because douchebag programmers keep getting obsessed with backwards dead-end bullshit like Markdown.

• Say it ain't so, Joe!

…my name's not Joe
@blakeyrat said:
Mostly I'm still bitter than it's 2015 and we have worse text editing options than we did in 2008, because douchebag programmers keep getting obsessed with backwards dead-end bullshit like Markdown.

That, and a lot of average people have a heart attack if they even see something as innocent as a <p> tag

<!-- Emoji'd by MobileEmoji 0.2.0-->

• If you go with Markdown, you're going to have the same Wikipedia problem where the only people who can tolerate/enjoy the process of editing an article

How so? I agree Wikipedia is a MESS - that's not Markdowns fault though surely? WikiMedias maybe...

• How so? I agree Wikipedia is a MESS - that's not Markdowns fault though surely? WikiMedias maybe...

I think his point is that both Markdown and MediaWikiCode both suck ass. MediaWikiCode is better, but that's like saying chlamydia is better than herpes; you don't really want either.

<!-- Emoji'd by MobileEmoji 0.2.0-->

• How so? I agree Wikipedia is a MESS - that's not Markdowns fault though surely? WikiMedias maybe...

No; it's a usability problem.

The only people who can successfully edit an article are the kind of pedantic dickweed a-holes you want kept away from a normal site. Because there's huge overlap between "pedantic dickweed a-holes" and "learning unnecessarily complicated bullshit".

I think his point is that both Markdown and MediaWikiCode both suck ass. MediaWikiCode is better, but that's like saying chlamydia is better than herpes; you don't really want either.

Exactly. Markdown is better, but it's not within 10,000 miles of "good".

• Exactly. Markdown is better, but it's not within 10,000 miles of "good".

Markdown is simpler, I'll give you that. Not sure it's correct to say it's better though; MediaWikiCode is a lot more powerful, from what I can tell.
How good is Markdown's table support?

<!-- Emoji'd by MobileEmoji 0.2.0-->

• How good is Markdown's table support?

Let's find out!

+-----------------+----------------+
|Tables | Suck |
+-----------------+----------------+

Oh look they suck.

Here's one copied from a GitHub "Markdown cheat sheet" page:

Tables Are Cool
col 3 is right-aligned $1600 col 2 is centered$12
zebra stripes are neat \$1

• From tablesgenerator.com:

GFM Markdown table syntax is quite simple. It does not allow row or cell spanning as well as putting multi-line text in a cell.

I think I'll stick with MediaWikiCode then; that can do all of those things, and a lot more besides

<!-- Emoji'd by MobileEmoji 0.2.0-->

• MediaWiki doesn't preclude a WYSIWYG editor, so I'm fine with that.

The point is, we've thoroughly proven Markdown is a piece of crap from both sides now, I think.

Again, the correct philosophy to have here is: if Discourse does it, you shouldn't.

• Apart from cross-topic post linking; that's actually quite useful

<!-- Emoji'd by MobileEmoji 0.2.0-->

• It's been said already but I'll say it again - don't use markdown.
Stick around here for more than 30 seconds, try to perform simple things in posts and see how many times something wrong happens.

• I think tables are disabled in Discourse markdown.

• I think tables are disabled in Discourse markdown.

On purpose, or just as a result of developer incompetence?

• Pretty sure it's on purpose. I recall bitching about it a while ago, and I think they said I was Doing It Wrong or something.

• markdown based wiki

If you're determined to use "Markdown", I would basically take advantage of the fact that there's no standardized version, and then you can fix all the annoyances with it:

1. Fix numbered lists so they start from the number the user specifies.
2. You can use _ for underlined text
3. Use a single * for bold and / for italic, and throw the irritating *** (or ___, yay!) in the bin
4. Fix all the terrible MD5 content injection hacks.
5. Don't require empty lines at random points in the user input to make their formatting work as intended.

Of course, you'll always run into situations where "Markdown" is too limited to express the formatting the user requires, so the suggested solution there is to allow users fall back into formatting based on both BBCode and HTML tags. Ideally, neither of these should work as you'd expect, and they should interact with each other in strange and unpredictable ways. So, I tied an onion to my belt, which was the style at the time. Now, to take the ferry cost a nickel, and in those days, nickels had pictures of bumblebees on 'em...

• Don't let the name fool you: Markdown is still a colossal mess markup language

<goats can't be grunty>

• I'm pretty sure there's no existing wiki software with that feature.

For sure, if you (@null_loop/you in general) want your software to be a success, finding a unique feature or point of differentiation from existing solutions is definitely the way to go.

Think about your 'elevator pitch': if you have 10 seconds to describe your wiki to someone, how do you summarize it? "It's the only wiki that does X". Solve for X.

Filed under: Consider replying to several posts at once? What am I? Batman?!

• 1. Fix numbered lists so they start from the number the user specifies.

1. You can use _ for underlined text
2. Use a single * for bold and / for italic, and throw the irritating *** (or ___, yay!) in the bin
3. Fix all the terrible MD5 content injection hacks.
4. Don't require empty lines at random points in the user input to make their formatting work as intended.

+1 plus the other annoyances which escape me now.

• Oh, and a somewhat-live preview - just don't go the Discourse way of having a JS port of your backend logic. I'd rather hit a "refresh" button which tells the server to render the snippet in question than amuse myself with inconsistencies between the "baked", "half-baked" and "totally baked" versions of the page.

Having a setInterval() to update the preview from the server every five (one? ten?) seconds or so might be something to think about. Then it's semi-live preview.

Or maybe keep a hash of the client-side content and check every 5 seconds, only bother the server if the content actually changed. You could also use the UI mark the preview as stale if the client-side content has changed since the last server update...

• Or a button.
I don't need an update live, or an update every 5 seconds or whatever. I want to make some changes, and then preview those.
Preview buttons work perfectly for that. It's a problem solved years ago that doesn't need re-engineering IMO.

• Wiki's that don't have mathjax support suck.

Edit: yes, all of them. Including tvtropes.

• Or a button.I don't need an update live, or an update every 5 seconds or whatever.

Agree to disagree? I'd find having to push a button for every tiny change to be more annoying than anything else. It practically guarantees that I'll publish my draft with unpreviewed changes...

• Confluence's WYSIWYG editor is very powerful and is backed by their own Wiki format.

Another thing Markdown doesn't have is layouts: like two or three columns.

• and front / back end parsers MUST match

• Use a fuzzer to test the front and back end parsers with a million random inputs, and check that the output is the same.
• Make the client send you the parser output, and re-parse it in the backend. If they don't match, make it automatically send a bug report to you.
• Write the parser in a more basic language and use a source-to-source compiler to translate it to both Javascript and ASP.NET

Looks like your connection to What the Daily WTF? was lost, please wait while we try to reconnect.