couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <...@apache.org>
Subject Re: CouchDB Wiki / Documentation
Date Sat, 06 Mar 2010 18:29:57 GMT

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





Mime
View raw message