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