Replies inline.
On 08/03/2012 07:59 AM, Justin Lebar wrote:
While I personally don't understand some people's fascination with MediaWiki
syntax (I can't stand it, myself), I know this is a Big Deal to some people.
Let me try to help you understand.
It's not an issue of being "fascinated" with MediaWiki syntax. (I
think markdown would be even better than MediaWiki syntax, myself.)
The issue, from my perspective, is that HTML is a horrible wiki markup
language, especially because our rich-text editor generates bad HTML.
(Fixing the rich-text editor to generate beautiful code would be Hard,
if not impossible.)
The source for MDN is /ugly/.
* "<a href="/en/HTML/HTML5" title="en/HTML/HTML5">main HTML5
page</a>". Why must we repeat the href in the link title in every
single link?
* Useless <p> </p> [1], <div style="width: auto;">'s [2]
scattered around for no reason.
* No whitespace between paragraphs, which makes the text impossible to
scan. (Whitespace between paragraphs is enforced by every wiki syntax
I've ever seen, and I see no whitespace between any paragraphs in the
MDN source, anywhere. In fact, I think the old wiki stripped it out.)
* < and > instead of < and > in code. This makes reading and
writing HTML examples particularly unpleasant. (Even if there is a
special hack in MDN to make < and > work inside code blocks, none of
the pages I looked at use it, which means the reading experience is
still affected.)
I could go on, and I'd be happy to if you still don't understand why I
feel that the plain-text editing experience in MDN is awful enough
that it's holding the wiki back from becoming great.
These are all issues that, in my view, are orthogonal to mediawiki
syntax and can be fixed.
You've said yourself that you edit MDN primarily using the rich text
editor and rarely edit the source, so I don't understand why you feel
strongly about this. I think perhaps if you tried to use the
plain-text editor for a week, you too might discover some of its
limitations.
Now, maybe your argument would be that everyone else should use the
rich text editor like you do, because it's an obviously-superior
experience. In that case, I'd suggest you just remove the ability to
edit the source directly, since there's no point in offering a
second-rate editing experience. But I think that would belie a
fundamental misunderstanding of your audience. It's the Mozilla
/Developer/ Network. Most of us produce machine-parsed text of some
form, by hand, in a plain-text editor, many hours a day. Plain text
is our chosen method of technical communication. It's hard for us to
get the rich-text editor to do what we want, and anyway, doing so
requires using the mouse (or leaning new keyboard shortcuts, if the
MDN rich-text editor has those?). We're HTML programmers who would be
ashamed to write such ugly HTML and can't stand reading it. Anyway we
are certainly no less technically inclined than the average Wikipedia
editor, so would have no trouble with whatever actual Wiki syntax you
chose.
If plain text were adequate for MDN, then we could use that. What you
want is a an easy way to produce HTML from plain text, e.g. markdown
(the concept, not the markdown-flavored markdown in particular). Do you
think that HTML is a good backing store for pages? If not, what should
they be? Should one particular form of markdown/wiki syntax "win"? What
do you do about tags a particular syntax doesn't support? What about
tables? I find them so fun to edit in any markdown syntax </sarcasm>
Surely you wouldn't suggest that a rich-text editor like FrontPage is
a good tool for developers of all skill levels to use when they edit
HTML. So I hope we can agree that the MDN rich text editor is not a
good tool for everyone.
I certainly agree here. FWIW, I am mostly fine editing HTML in a
textbox. I edit HTML by hand all over the place anyway.
I understand that this seems like a bikeshed. I'm a grumpy programmer
with an opinion. But I don't think this is a trivial issue. After
the stability issues, which perhaps are now fixed, the HTML ugliness
is the primary reason I avoid MDN at all costs. It sounds like I'm
not alone.
Do you often hear people say they're drawn to MDN because of the
awesome plain-text editing experience? If not, on what basis do you
make the argument that the plain-text editing experience on MDN is
better than it would be under a different syntax regime? Conversely,
do you often hear programmers complain that Github uses Markdown
instead of HTML? Surely if HTML was right for MDN, it would be right
for Github bug reports too. Why aren't more sites for developers
following MDN's lead and using HTML for user-generated content, do you
think? Is it your view that they are all misguided, or otherwise
misunderstand their audience?
So there are several different things here. For translating text to
HTML, markdown is a fair choice, since READMEs may be in markdown. (Mine
often aren't, forcing me to adjust the way I do things for github, which
is one thing I would complain about). By choosing plain text -- not
mediawiki, not markdown -- bugzilla speaks to what you spoke of earlier:
that as developers, we communicate in text. It also avoids the debate
(sorta) of "bugzilla should support markdown" or "bugzilla should
support mediawiki" etc. Plain text is not adequate for MDN. As far as
mediawiki being universal, I and others have historically avoided
contributing to e.g. wikipedia because of complexities like editing
tables in mediawiki.
That said, we know that there are people that prefer MediaWiki and we'll see if
we can find a way to let people use some kind of tool that lets them paste
MediaWiki syntax in and get it automatically converted into HTML.
Editing is an important function of a wiki, so this would be pretty
unsatisfying. I agree with the implicit argument here that a lossless
HTML <--> MediaWiki (or whatever) translator would be difficult, and
since it would have to push all of the ugliness present in MDN's
existing HTML into the resultant MediaWiki text, I'm not convinced the
result would be a big improvement. So long as HTML is the canonical
language, I do not think we are going to solve this problem.
We're on the same side here: We both want MDN to be great. Even if I
haven't convinced you, I hope I've made clear the argument against how
things are now.
-Justin
[1]
https://developer-new.mozilla.org/en-US/docs/HTML/HTML5/Introduction_to_HTML5$edit
[2]
https://developer-new.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array$edit
Disclaimer: I am not affiliated with mdndev at all. Just dissenting
opinions from the peanut gallery
On Fri, Aug 3, 2012 at 8:31 AM, Sheppy <[email protected]> wrote:
On Friday, August 3, 2012 12:02:10 AM UTC-4, Benoit Jacob wrote:
The #1 problem for many people with the current MDN wiki was that it didn't
offer mediawiki-compatible markup editing. It would be great to be able to
use right away one's familiarity with mediawiki markup (which is what most
people know), and of course being able to copy and paste contents to/from
mediawikis would be a huge benefit of that. Will the new wiki system offer
that? Sorry, I hadn't heard of Kuma and a google search for Kuma Wiki
didn't return useful results.
Kuma continues to use HTML as its markup language; this is a universally-known
standard that we think makes sense. Switching back to MediaWiki markup was not
a viable option after years of using standard HTML.
While I personally don't understand some people's fascination with MediaWiki
syntax (I can't stand it, myself), I know this is a Big Deal to some people.
Unfortunately, there was no way to satisfy everyone, and we had to make a
decision. In the end, for both technical and social reasons (more people know
and like HTML than MediaWiki syntax -- indeed, I bet you know HTML yourself),
it just made more sense to use HTML.
That said, we know that there are people that prefer MediaWiki and we'll see if
we can find a way to let people use some kind of tool that lets them paste
MediaWiki syntax in and get it automatically converted into HTML. But that's
not going to happen right away, since there are still some more fundamental
site features we need to work on.
I know this is frustrating to some people that prefer MediaWiki syntax, and
we'll see what we can do. I just can't make any promises, and obviously
anything we do manage to do won't be the same as a raw MediaWiki setup.
I'm surprised you hadn't heard of Kuma; we've been talking about it at length
for over a year, including posts to this very mailing list asking for people to
help us test it. This makes me feel sad since we worked so hard to get the word
out. :)
Eric Shepherd
Developer Documentation Lead
Mozilla
http://www.bitstampede.com/
_______________________________________________
dev-platform mailing list
[email protected]
https://lists.mozilla.org/listinfo/dev-platform
_______________________________________________
dev-platform mailing list
[email protected]
https://lists.mozilla.org/listinfo/dev-platform
_______________________________________________
dev-platform mailing list
[email protected]
https://lists.mozilla.org/listinfo/dev-platform
