couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Dionne <dio...@dionne-associates.com>
Subject Re: CouchDB Wiki / Documentation
Date Sun, 07 Mar 2010 14:50:49 GMT


On Mar 7, 2010, at 3:11 AM, J Chris Anderson wrote:

> 
> On Mar 6, 2010, at 4:47 PM, Noah Slater wrote:
> 
>> 
>> On 7 Mar 2010, at 00:38, Mikeal Rogers wrote:
>> 
>>> We can provide the same providence and copyright assurances outside of
>>> JIRA. It's a checkbox, it's not hard.
>> 
>> I agree. I don't want to be misunderstood as fighting against the initiative of improving
our documentation. I just want to make sure we do it in a way that embraces our parent organisation.
And as far as I know, and I am incorrect rather frequently, that involves hosting whatever
we use on ASF infrastructure, and taking the proper measures to make sure that what is produced
is free for the community to use, where free is the ASF's definition of free. If we can satisfy
that, and improve our documentation, it will have my full support. However, just creating
a new repository on Github and linking to it from our site is not satisfactory.
> 
> I think the short run, putting together an informal Markdown repository of docs or proto-docs
would be cool. I don't care where it live but we'll need to get an ASF Zone for a project
CouchDB instance. I guess this means Damien has to send an email to infra.
> 
> It's simple to have CouchDB render Markdown. After 0.11 is out and we launch the project
CouchDB instance, I'm sure there are a ton of CouchApps we could run it on that can handle
Markdown.

I really like the idea of this dogfood exercise. With respect to Markdown, I'd like to also
mention Org for those who are emacs users. It can be used for everything from project management
to publishing web pages, journal articles, you name it. One can even embed LaTex in it. For
those who already know Org, markdown-mode[1] enables editing of markdown with org style cycling,
etc.. it can be published to any format.

I think the closer to doc stays to the code the more apt it is to be read, written, and useful.
I'm wondering how useful it might be to have some of these markdown files reside with the
code in the repository.


[1] http://jblevins.org/projects/markdown-mode/





> 
> Under ASF guidelines I'm pretty sure we don't need to worry about CLAs for documentation
contributors. Let's get the barrier to entry for new documenters as low as possible.
> 
> Chris
> 
> 


Mime
View raw message