If the point is to replace the wiki then it needs to be *easier* than the wiki for people who aren't committers.
The big advantage to markdown is that you can parse it to HTML in a strict mode that will escape any HTML in the original text makeing it a lot easier to take contributions from people who sign up for accounts without worrying about malicious content and some spam. -Mikeal On Sat, Mar 6, 2010 at 10:29 AM, Jan Lehnardt <[email protected]> wrote: > > On 6 Mar 2010, at 09:26, Noah Slater wrote: > >> >> On 6 Mar 2010, at 17:20, Robert Dionne wrote: >> >>> +1 on markdown. I find writing docs in markdown to push to github from >>> emacs very productive. >> >> It also introduces a generation step. >> >> Static HTML files can be served up without any need to process them. >> >>> With markdown you only have to remember about 5 things to get 80% of the >>> job done. >> >> And, like all "plain text" formats, the other 20% are 80% harder to do than >> with HTML. > > I do have to side with Noah here on this argument. When we wrote CouchDB: The > Definitive Guide, we started out using asciidoc (feel roughly like Markdown, > has more markup possibilities which made it look more suitable for a book). > While starting out was pretty easy, it got a bit of pain to get all the > conversions right (Noah did most of that work). For further work on the book, > we're writing straight HTML and I think it is a good idea. > > If we can define a subset of HTML to be used to structure the docs, it's not > much more painful than editing Markdown. I don't see this as an obstacle. > > However, Markdown still feels more right to me. The beauty is, that if we > figure out it sucks, we can still take the produced HTML, tidy and xslt-clean > it (if needed) and continue to work on the HTML. > > I'd say let's start with Markdown and see where and when it fails. > > Cheers > Jan > -- > > > > >
