couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mikeal Rogers <mikeal.rog...@gmail.com>
Subject Re: CouchDB Wiki / Documentation
Date Sat, 06 Mar 2010 19:34:16 GMT
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 <jan@apache.org> 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
> --
>
>
>
>
>

Mime
View raw message