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 --
