Re: Tutorial - request for feedback

On 18 June 2014 22:51, Rowan Collins <rowan.collins@gmail.com> wrote: > On 16/06/2014 16:22, Chris Wright wrote: >> >> I agree 100% on the wiki syntax vs. markdown in terms of which one is >> nicer to work with, this is a very valid point. > > > Just out of curiosity, what is it, other than familiarity from other places, > that makes you like Markdown more than DokuWiki's syntax? (I think that's > the wiki in question?) > > I've not really used DokuWiki, but it looks like a fairly sensible markup - > perhaps because I'm so used to MediaWiki (e.g. Wikipedia), and it feels like > a tidied up version of that. Markdown co-opts a lot of single punctuation > characters, meaning you end up with inadvertent formatting (e.g. if you > write a_name_with_underscores); DokuWiki seems to mostly only look at > *repeated* punctuation, making formatting much more deliberate. And I always > struggle to get the square and round brackets the right way round with > Markdown's link syntax... I think it's mostly a case of lowest common denominator - it's a fairly safe assumption that most of our contributors are also at least casual users of Stack Exchange and Github, especially the latter as most of the PHP project's repositories have mirrors on Github (except doc sources, hint hint :-P). Personally I always found docuwiki to be a little clunky, and I've never had too much of an issue with the accidental formatting you describe - and to counter your point about a_name_with_underscores, I think you need a better markdown rendering engine ;-) That said, this is a highly subjective opinion and if we don't have unanimity we should probably vote on it in some way. As I hinted at (although reading it back, never actually said) in my first reply to this thread, for me an important point about unifying things is that we actually unify them - we're putting information in one place, we should probably aim to put the maintenance systems into a single format as well, which was one of my motivations for suggesting that this become a wiki page. ...but I like markdown, I find the wiki more difficult to use, so I'm a bit torn on this point - reading my own responses over it's clear that even I'm not sure what I think :-(