You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@couchdb.apache.org by Dave Cottlehuber <da...@muse.net.nz> on 2011/11/22 15:08:35 UTC
[VOTE] Apache CouchDB new docs proposal
Hi devs,
Over the last two years we've discussed improving our documentation, website,
and wiki. We have discussed several designs ad mortem[1]…[5], and while the
wiki has evolved substantially, not much else has changed.
This proposal summarises a consensus direction, and puts forward an approach
that should allow us to improve docs in incremental stages with the usual
peer review process for the actual patches/changes.
NB this is readable as markdown on https://gist.github.com/gists/1385728
# Apache CouchDB Docs Spruce-Up
CouchDB's documentation (wiki, API docs, and website) reflects its rapid
evolution. We need a spruce up!
The plan is:
- nominate a PMC owner (nslater)
- update the website (dch)
- tidy up the wiki (anybody?)
- implement docbook for APIs etc
## Update the CouchDB.org[0] website
"The design is less important than the content." J Chris Anderson
Previous work has stopped at the design stage, rather than getting the content.
### Phase 1
- select one of the previously worked designs[0]..[5] and migrate current
content into it
### Phase 2
- review all pages and update as needed
- make it easy to navigate to key content (even if not in same site)
- overview, use case & philosophy
- source, roadmap
- API docs, wiki
- mailing lists/archives
- community contributions incl tools & tutorials, blogs, stories, binaries
- links to hosting & commercial support
### Phase 3
- check if any of the commercial vendors would be willing to fund a designer
## Tidy up the wiki
- add a page which lists all pages
- ask people to own reviewing each page
- get writing/restructuring/pruning
## Implement DocBook
- jan to clarify what's available from CouchBase
- nslater to look at implementing this, or failing that something else
- ask community for ideas for overall chapter structure
- get an owner for each chapter + solicit contributions from community
- get writing ...
- develop guidelines a la existing Release Procedure for doc contributions
to patches, releases, and commits
I would like to call a vote[6],[7] for the above proposal. Feel free to
read the existing emails on this subject [8][9][10].
We encourage the whole community to review and give feedback -- everyone is
free to vote on this proposal, so get stuck in!
Happy voting,
Dave Cottlehuber
https://github.com/dch
"Can we just commit this and work on any remaining details that
someone wants to put in effort to fix?"
"I think a big part of Rails' early success was the website:
http://rubyonrails.org/"
"The design is less important than the content."
"Having all the blog posts, wikis, videos, case-studies, IRC logs,
screen-casts, etc. available in a an easy-to-digest website, will make
no-hassle for newcomers, which is the most important thing."
"make it easy for new arrivals to find just what they need to know about
CouchDB, while at the same time giving them a taste of the "Relax" feeling."
## references
- current [0]: http://www.couchdb.org/
- classic [1]:
http://people.apache.org/~jan/couchdb.org.new/couch-classic/htdocs/
- minimal [2]:
http://people.apache.org/~jan/couchdb.org.new/couch-site/htdocs/
- kriesse [3]: https://github.com/Kriesse/couchdb_web or view at
https://www.dropbox.com/s/oq0bd9w7ufb0a3b/CouchDB/tmp/new_websites/kriesse/index.html
- eegg [4]: https://github.com/eegg/couchdb_web or view at
https://www.dropbox.com/s/oq0bd9w7ufb0a3b/CouchDB/tmp/new_websites/eegg/index.html
- lean [5]: http://jan.prima.de/couchdb_web/
- voting: [6]: http://www.apache.org/foundation/voting.html
- release: [7]: http://wiki.apache.org/couchdb/Release_procedure
- website [8]: http://bit.ly/rTt0kV
- wiki [9]: http://bit.ly/vJDITc
- docs [10]: http://bit.ly/ufasCB
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Dave Cottlehuber <da...@muse.net.nz>.
On 23 November 2011 09:10, Randall Leeds <ra...@gmail.com> wrote:
> +1
>
> Regarding the wiki cleanup efforts, I've already volunteered to
> organize some wiki sprints. I will start doing so over the next week
> or two.
Awesome Randall!
We had a bit of a bash earlier this week too - thanks Jan & Robert and
any others who dug into this. I hear rumours of a regular Wiki Friday
on IRC - this would be a great step forwards.
I'm happy to help on this also.
A+
Dave
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Randall Leeds <ra...@gmail.com>.
+1
Regarding the wiki cleanup efforts, I've already volunteered to
organize some wiki sprints. I will start doing so over the next week
or two.
On Tue, Nov 22, 2011 at 09:08, Dave Cottlehuber <da...@muse.net.nz> wrote:
> Hi devs,
>
> Over the last two years we've discussed improving our documentation, website,
> and wiki. We have discussed several designs ad mortem[1]…[5], and while the
> wiki has evolved substantially, not much else has changed.
>
> This proposal summarises a consensus direction, and puts forward an approach
> that should allow us to improve docs in incremental stages with the usual
> peer review process for the actual patches/changes.
>
> NB this is readable as markdown on https://gist.github.com/gists/1385728
>
> # Apache CouchDB Docs Spruce-Up
>
> CouchDB's documentation (wiki, API docs, and website) reflects its rapid
> evolution. We need a spruce up!
>
> The plan is:
>
> - nominate a PMC owner (nslater)
> - update the website (dch)
> - tidy up the wiki (anybody?)
> - implement docbook for APIs etc
>
> ## Update the CouchDB.org[0] website
>
> "The design is less important than the content." J Chris Anderson
>
> Previous work has stopped at the design stage, rather than getting the content.
>
> ### Phase 1
> - select one of the previously worked designs[0]..[5] and migrate current
> content into it
>
> ### Phase 2
>
> - review all pages and update as needed
> - make it easy to navigate to key content (even if not in same site)
> - overview, use case & philosophy
> - source, roadmap
> - API docs, wiki
> - mailing lists/archives
> - community contributions incl tools & tutorials, blogs, stories, binaries
> - links to hosting & commercial support
>
> ### Phase 3
> - check if any of the commercial vendors would be willing to fund a designer
>
> ## Tidy up the wiki
> - add a page which lists all pages
> - ask people to own reviewing each page
> - get writing/restructuring/pruning
>
> ## Implement DocBook
> - jan to clarify what's available from CouchBase
> - nslater to look at implementing this, or failing that something else
> - ask community for ideas for overall chapter structure
> - get an owner for each chapter + solicit contributions from community
> - get writing ...
> - develop guidelines a la existing Release Procedure for doc contributions
> to patches, releases, and commits
>
> I would like to call a vote[6],[7] for the above proposal. Feel free to
> read the existing emails on this subject [8][9][10].
>
> We encourage the whole community to review and give feedback -- everyone is
> free to vote on this proposal, so get stuck in!
>
> Happy voting,
> Dave Cottlehuber
> https://github.com/dch
>
> "Can we just commit this and work on any remaining details that
> someone wants to put in effort to fix?"
>
> "I think a big part of Rails' early success was the website:
> http://rubyonrails.org/"
>
> "The design is less important than the content."
>
> "Having all the blog posts, wikis, videos, case-studies, IRC logs,
> screen-casts, etc. available in a an easy-to-digest website, will make
> no-hassle for newcomers, which is the most important thing."
>
> "make it easy for new arrivals to find just what they need to know about
> CouchDB, while at the same time giving them a taste of the "Relax" feeling."
>
> ## references
>
> - current [0]: http://www.couchdb.org/
> - classic [1]:
> http://people.apache.org/~jan/couchdb.org.new/couch-classic/htdocs/
> - minimal [2]:
> http://people.apache.org/~jan/couchdb.org.new/couch-site/htdocs/
> - kriesse [3]: https://github.com/Kriesse/couchdb_web or view at
> https://www.dropbox.com/s/oq0bd9w7ufb0a3b/CouchDB/tmp/new_websites/kriesse/index.html
> - eegg [4]: https://github.com/eegg/couchdb_web or view at
> https://www.dropbox.com/s/oq0bd9w7ufb0a3b/CouchDB/tmp/new_websites/eegg/index.html
> - lean [5]: http://jan.prima.de/couchdb_web/
>
> - voting: [6]: http://www.apache.org/foundation/voting.html
> - release: [7]: http://wiki.apache.org/couchdb/Release_procedure
>
> - website [8]: http://bit.ly/rTt0kV
> - wiki [9]: http://bit.ly/vJDITc
> - docs [10]: http://bit.ly/ufasCB
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Noah Slater <ns...@tumbolia.org>.
Sure.
Well, I'd like to link to the docs from the website. And some amount of
basic typesetting would be nice. HTML is the bare minimum if we want text
(obviously) and hyperlinks. I think hyperlinks would be useful. Even if
it's only so we can use anchors.
If you look at the source of the CouchDB book, we could strip HTML down to
its barest elements. The "administrative debris" like navigation, style,
etc can be added with a single common JavaScript file and a single common
CSS file.
If we want to move forward with this, I am happy to drive the effort.
Our first steps should be:
- Get some plain text only documentation together from the committers
- Speak to Infra about how to host the documentation
If someone can co-ordinate the first point, I can take this stuff and shape
it in to some basic HTML for us to use.
I can take care of the second item.
On Sat, Nov 26, 2011 at 7:53 PM, Robert Newson <rn...@apache.org> wrote:
> Noah: All I really mean is that the docs/ are widely available. If
> it's infeasible to push them to the wiki then let's not do it, but I'd
> be surprised if that's a technical challenge for a group with our
> diverse superpowers.
>
> As for choice of markup language, I have no preference. What's the
> minimum here? Do we need more than just plain text? The linux kernel's
> Documentation/ dir seems to get away with it.
>
> B.
>
> On 26 November 2011 19:47, Dave Cottlehuber <da...@muse.net.nz> wrote:
> > On 26 November 2011 14:25, Robert Dionne <di...@dionne-associates.com>
> wrote:
> >> +1 for Latex
> >
> > Hi Robert, all,
> >
> > Thanks for taking the time to read all that!
> >
> > Specific design & tools aside, are you willing to support at least the
> > principle of upgrading/improvement of the documentation?
> >
> > Or are you fundamentally against docbook? Personally, I am agnostic on
> > the tool but I would like to know that I can contribute something that
> > won't require rework in future, and I'll happily learn tool X to
> > support that.
> >
> > I see little point in counting a few +1 votes and then making
> > wholesale changes; this should be a consensus otherwise I'd rather
> > revert to incremental changes to the wiki.
> >
> > A+
> > Dave
> >
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Robert Newson <rn...@apache.org>.
Noah: All I really mean is that the docs/ are widely available. If
it's infeasible to push them to the wiki then let's not do it, but I'd
be surprised if that's a technical challenge for a group with our
diverse superpowers.
As for choice of markup language, I have no preference. What's the
minimum here? Do we need more than just plain text? The linux kernel's
Documentation/ dir seems to get away with it.
B.
On 26 November 2011 19:47, Dave Cottlehuber <da...@muse.net.nz> wrote:
> On 26 November 2011 14:25, Robert Dionne <di...@dionne-associates.com> wrote:
>> +1 for Latex
>
> Hi Robert, all,
>
> Thanks for taking the time to read all that!
>
> Specific design & tools aside, are you willing to support at least the
> principle of upgrading/improvement of the documentation?
>
> Or are you fundamentally against docbook? Personally, I am agnostic on
> the tool but I would like to know that I can contribute something that
> won't require rework in future, and I'll happily learn tool X to
> support that.
>
> I see little point in counting a few +1 votes and then making
> wholesale changes; this should be a consensus otherwise I'd rather
> revert to incremental changes to the wiki.
>
> A+
> Dave
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Robert Dionne <di...@dionne-associates.com>.
On Nov 26, 2011, at 2:47 PM, Dave Cottlehuber wrote:
> On 26 November 2011 14:25, Robert Dionne <di...@dionne-associates.com> wrote:
>> +1 for Latex
>
> Hi Robert, all,
>
> Thanks for taking the time to read all that!
>
> Specific design & tools aside, are you willing to support at least the
> principle of upgrading/improvement of the documentation?
Yes of course, I'm not fundamentally opposed to any technology. I was only seconding the suggestion of the use of LaTEX as I find it superior to docbook in every way. It seems to me that if we want
the programmers to contribute a lot of this content then something like Markdown, Org, or even just plain text would be the easiest
>
> Or are you fundamentally against docbook? Personally, I am agnostic on
> the tool but I would like to know that I can contribute something that
> won't require rework in future, and I'll happily learn tool X to
> support that.
>
> I see little point in counting a few +1 votes and then making
> wholesale changes; this should be a consensus otherwise I'd rather
> revert to incremental changes to the wiki.
>
> A+
> Dave
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Dave Cottlehuber <da...@muse.net.nz>.
On 26 November 2011 14:25, Robert Dionne <di...@dionne-associates.com> wrote:
> +1 for Latex
Hi Robert, all,
Thanks for taking the time to read all that!
Specific design & tools aside, are you willing to support at least the
principle of upgrading/improvement of the documentation?
Or are you fundamentally against docbook? Personally, I am agnostic on
the tool but I would like to know that I can contribute something that
won't require rework in future, and I'll happily learn tool X to
support that.
I see little point in counting a few +1 votes and then making
wholesale changes; this should be a consensus otherwise I'd rather
revert to incremental changes to the wiki.
A+
Dave
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Robert Dionne <di...@dionne-associates.com>.
+1 for Latex
On Nov 26, 2011, at 8:22 AM, Benoit Chesneau wrote:
> On Sat, Nov 26, 2011 at 6:09 AM, Kristina Schneider <
> mail@kristinaschneider.com> wrote:
>
>> Whatever you are voting on, happy to see some activity on these old
>> designs getting implemented :)
>>
>> Noah, let me know if / how I can help and I'll see if I can free up some
>> hours for that!
>>
>> Kriesse
>>
>>
>>
>> On Nov 25, 2011, at 3:13 PM, Noah Slater wrote:
>>
>>> I seem to be missing the start of this thread.
>>>
>>> What are we voting on?
>>>
>>> I am happy to lead the way on getting this implemented, and dealing with
>> people's requests, and saying no a lot, and all the other things you have
>> to do when you're trying to avoid designing by committee. But to do that,
>> I'm going to need a designer to help me turn these from mockups into
>> working HTML and CSS for a fully functional site, with each page nicely set
>> out.
>>>
>>> Copying in kriesse and eegg, on the off chance that either of them have
>> the cycles to devote to this. ;)
>>>
>>> On Wed, Nov 23, 2011 at 1:23 PM, Robert Newson <rn...@apache.org>
>> wrote:
>>> +1
>>>
>>> On 23 November 2011 10:31, Dave Cottlehuber <da...@muse.net.nz> wrote:
>>>> On 22 November 2011 15:08, Dave Cottlehuber <da...@muse.net.nz> wrote:
>>>>
>>>> Sorry, seems none of my dropbox links are working this week.
>>>>
>>>> Here are the eegg and kriesse versions with links to a couch like I
>>>> should be doing …. Gist also updated.
>>>>
>>>>> Hi devs,
>>>>> ## references
>>>>
>>>> - kriesse [3]: https://github.com/Kriesse/couchdb_web or view at
>>>>
>> http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/kriesse_couch_web/index.html
>>>> - eegg [4]: https://github.com/eegg/couchdb_web or view at
>>>>
>> http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/eegg_couch_web/index.html
>>>>
>>>> A+
>>>> Dave
>>>>
>>>
>>
>> btw for my guide I will use dexy [1] . Maybe it can be used for the doc? I
> always found latex easier than docbook somehow. What do you think?
>
> - benoît
>
>
> [1] http://www.dexy.it/
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Benoit Chesneau <bc...@gmail.com>.
On Sat, Nov 26, 2011 at 6:09 AM, Kristina Schneider <
mail@kristinaschneider.com> wrote:
> Whatever you are voting on, happy to see some activity on these old
> designs getting implemented :)
>
> Noah, let me know if / how I can help and I'll see if I can free up some
> hours for that!
>
> Kriesse
>
>
>
> On Nov 25, 2011, at 3:13 PM, Noah Slater wrote:
>
> > I seem to be missing the start of this thread.
> >
> > What are we voting on?
> >
> > I am happy to lead the way on getting this implemented, and dealing with
> people's requests, and saying no a lot, and all the other things you have
> to do when you're trying to avoid designing by committee. But to do that,
> I'm going to need a designer to help me turn these from mockups into
> working HTML and CSS for a fully functional site, with each page nicely set
> out.
> >
> > Copying in kriesse and eegg, on the off chance that either of them have
> the cycles to devote to this. ;)
> >
> > On Wed, Nov 23, 2011 at 1:23 PM, Robert Newson <rn...@apache.org>
> wrote:
> > +1
> >
> > On 23 November 2011 10:31, Dave Cottlehuber <da...@muse.net.nz> wrote:
> > > On 22 November 2011 15:08, Dave Cottlehuber <da...@muse.net.nz> wrote:
> > >
> > > Sorry, seems none of my dropbox links are working this week.
> > >
> > > Here are the eegg and kriesse versions with links to a couch like I
> > > should be doing …. Gist also updated.
> > >
> > >> Hi devs,
> > >> ## references
> > >
> > > - kriesse [3]: https://github.com/Kriesse/couchdb_web or view at
> > >
> http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/kriesse_couch_web/index.html
> > > - eegg [4]: https://github.com/eegg/couchdb_web or view at
> > >
> http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/eegg_couch_web/index.html
> > >
> > > A+
> > > Dave
> > >
> >
>
> btw for my guide I will use dexy [1] . Maybe it can be used for the doc? I
always found latex easier than docbook somehow. What do you think?
- benoît
[1] http://www.dexy.it/
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Kristina Schneider <ma...@kristinaschneider.com>.
Whatever you are voting on, happy to see some activity on these old designs getting implemented :)
Noah, let me know if / how I can help and I'll see if I can free up some hours for that!
Kriesse
On Nov 25, 2011, at 3:13 PM, Noah Slater wrote:
> I seem to be missing the start of this thread.
>
> What are we voting on?
>
> I am happy to lead the way on getting this implemented, and dealing with people's requests, and saying no a lot, and all the other things you have to do when you're trying to avoid designing by committee. But to do that, I'm going to need a designer to help me turn these from mockups into working HTML and CSS for a fully functional site, with each page nicely set out.
>
> Copying in kriesse and eegg, on the off chance that either of them have the cycles to devote to this. ;)
>
> On Wed, Nov 23, 2011 at 1:23 PM, Robert Newson <rn...@apache.org> wrote:
> +1
>
> On 23 November 2011 10:31, Dave Cottlehuber <da...@muse.net.nz> wrote:
> > On 22 November 2011 15:08, Dave Cottlehuber <da...@muse.net.nz> wrote:
> >
> > Sorry, seems none of my dropbox links are working this week.
> >
> > Here are the eegg and kriesse versions with links to a couch like I
> > should be doing …. Gist also updated.
> >
> >> Hi devs,
> >> ## references
> >
> > - kriesse [3]: https://github.com/Kriesse/couchdb_web or view at
> > http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/kriesse_couch_web/index.html
> > - eegg [4]: https://github.com/eegg/couchdb_web or view at
> > http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/eegg_couch_web/index.html
> >
> > A+
> > Dave
> >
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Dave Cottlehuber <da...@muse.net.nz>.
On 26 November 2011 05:43, Noah Slater <ns...@tumbolia.org> wrote:
> These two projects are orthogonal to each other:
>
> Project 1: Getting code/API docs bundled in the source distribution.
>
> Project 2: Getting a new website design in place.
>
> On Sat, Nov 26, 2011 at 1:36 AM, Marco Monteiro <ma...@textovirtual.com>wrote:
>
>> Can the first step be to get the docbook api documentation in the repo and
>> start from that? Any plan that delays that step is not as good.
Agreed, and I'm very keen to treat them as such. Perhaps phases is not
the best word in hindsight.
A+
Dave
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Noah Slater <ns...@tumbolia.org>.
These two projects are orthogonal to each other:
Project 1: Getting code/API docs bundled in the source distribution.
Project 2: Getting a new website design in place.
On Sat, Nov 26, 2011 at 1:36 AM, Marco Monteiro <ma...@textovirtual.com>wrote:
> Can the first step be to get the docbook api documentation in the repo and
> start from that? Any plan that delays that step is not as good.
>
> On 25 November 2011 23:13, Noah Slater <ns...@tumbolia.org> wrote:
>
> > I seem to be missing the start of this thread.
> >
> > What are we voting on?
> >
> > I am happy to lead the way on getting this implemented, and dealing with
> > people's requests, and saying no a lot, and all the other things you have
> > to do when you're trying to avoid designing by committee. But to do that,
> > I'm going to need a designer to help me turn these from mockups into
> > working HTML and CSS for a fully functional site, with each page nicely
> set
> > out.
> >
> > Copying in kriesse and eegg, on the off chance that either of them have
> the
> > cycles to devote to this. ;)
> >
> > On Wed, Nov 23, 2011 at 1:23 PM, Robert Newson <rn...@apache.org>
> wrote:
> >
> > > +1
> > >
> > > On 23 November 2011 10:31, Dave Cottlehuber <da...@muse.net.nz> wrote:
> > > > On 22 November 2011 15:08, Dave Cottlehuber <da...@muse.net.nz>
> wrote:
> > > >
> > > > Sorry, seems none of my dropbox links are working this week.
> > > >
> > > > Here are the eegg and kriesse versions with links to a couch like I
> > > > should be doing …. Gist also updated.
> > > >
> > > >> Hi devs,
> > > >> ## references
> > > >
> > > > - kriesse [3]: https://github.com/Kriesse/couchdb_web or view at
> > > >
> > >
> >
> http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/kriesse_couch_web/index.html
> > > > - eegg [4]: https://github.com/eegg/couchdb_web or view at
> > > >
> > >
> >
> http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/eegg_couch_web/index.html
> > > >
> > > > A+
> > > > Dave
> > > >
> > >
> >
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Marco Monteiro <ma...@textovirtual.com>.
Can the first step be to get the docbook api documentation in the repo and
start from that? Any plan that delays that step is not as good.
On 25 November 2011 23:13, Noah Slater <ns...@tumbolia.org> wrote:
> I seem to be missing the start of this thread.
>
> What are we voting on?
>
> I am happy to lead the way on getting this implemented, and dealing with
> people's requests, and saying no a lot, and all the other things you have
> to do when you're trying to avoid designing by committee. But to do that,
> I'm going to need a designer to help me turn these from mockups into
> working HTML and CSS for a fully functional site, with each page nicely set
> out.
>
> Copying in kriesse and eegg, on the off chance that either of them have the
> cycles to devote to this. ;)
>
> On Wed, Nov 23, 2011 at 1:23 PM, Robert Newson <rn...@apache.org> wrote:
>
> > +1
> >
> > On 23 November 2011 10:31, Dave Cottlehuber <da...@muse.net.nz> wrote:
> > > On 22 November 2011 15:08, Dave Cottlehuber <da...@muse.net.nz> wrote:
> > >
> > > Sorry, seems none of my dropbox links are working this week.
> > >
> > > Here are the eegg and kriesse versions with links to a couch like I
> > > should be doing …. Gist also updated.
> > >
> > >> Hi devs,
> > >> ## references
> > >
> > > - kriesse [3]: https://github.com/Kriesse/couchdb_web or view at
> > >
> >
> http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/kriesse_couch_web/index.html
> > > - eegg [4]: https://github.com/eegg/couchdb_web or view at
> > >
> >
> http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/eegg_couch_web/index.html
> > >
> > > A+
> > > Dave
> > >
> >
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Noah Slater <ns...@tumbolia.org>.
I seem to be missing the start of this thread.
What are we voting on?
I am happy to lead the way on getting this implemented, and dealing with
people's requests, and saying no a lot, and all the other things you have
to do when you're trying to avoid designing by committee. But to do that,
I'm going to need a designer to help me turn these from mockups into
working HTML and CSS for a fully functional site, with each page nicely set
out.
Copying in kriesse and eegg, on the off chance that either of them have the
cycles to devote to this. ;)
On Wed, Nov 23, 2011 at 1:23 PM, Robert Newson <rn...@apache.org> wrote:
> +1
>
> On 23 November 2011 10:31, Dave Cottlehuber <da...@muse.net.nz> wrote:
> > On 22 November 2011 15:08, Dave Cottlehuber <da...@muse.net.nz> wrote:
> >
> > Sorry, seems none of my dropbox links are working this week.
> >
> > Here are the eegg and kriesse versions with links to a couch like I
> > should be doing …. Gist also updated.
> >
> >> Hi devs,
> >> ## references
> >
> > - kriesse [3]: https://github.com/Kriesse/couchdb_web or view at
> >
> http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/kriesse_couch_web/index.html
> > - eegg [4]: https://github.com/eegg/couchdb_web or view at
> >
> http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/eegg_couch_web/index.html
> >
> > A+
> > Dave
> >
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Robert Newson <rn...@apache.org>.
+1
On 23 November 2011 10:31, Dave Cottlehuber <da...@muse.net.nz> wrote:
> On 22 November 2011 15:08, Dave Cottlehuber <da...@muse.net.nz> wrote:
>
> Sorry, seems none of my dropbox links are working this week.
>
> Here are the eegg and kriesse versions with links to a couch like I
> should be doing …. Gist also updated.
>
>> Hi devs,
>> ## references
>
> - kriesse [3]: https://github.com/Kriesse/couchdb_web or view at
> http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/kriesse_couch_web/index.html
> - eegg [4]: https://github.com/eegg/couchdb_web or view at
> http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/eegg_couch_web/index.html
>
> A+
> Dave
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Dave Cottlehuber <da...@muse.net.nz>.
On 22 November 2011 15:08, Dave Cottlehuber <da...@muse.net.nz> wrote:
Sorry, seems none of my dropbox links are working this week.
Here are the eegg and kriesse versions with links to a couch like I
should be doing …. Gist also updated.
> Hi devs,
> ## references
- kriesse [3]: https://github.com/Kriesse/couchdb_web or view at
http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/kriesse_couch_web/index.html
- eegg [4]: https://github.com/eegg/couchdb_web or view at
http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/eegg_couch_web/index.html
A+
Dave
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Noah Slater <ns...@tumbolia.org>.
Cool.
For now then, I'd say we wait for an update from Couchbase before moving
forward.
If people want to jot down their ideas on the wiki page I created, I think
that would be productive.
http://wiki.apache.org/couchdb/SourceDocumentation
On Sun, Nov 27, 2011 at 7:19 PM, Jan Lehnardt <ja...@apache.org> wrote:
>
> On Nov 27, 2011, at 13:10 , Marco Monteiro wrote:
>
> > I was under the impression that CouchBase might be available to give
> their
> > (docbook) documentation to the project so that it can be used as the
> > starting point. This would spare the community a lot of the work.
> >
> > Jan, is this still possible, and can it be worked out so that the
> > documentation
> > is in couchdb repo before, lets say, the end of the year?
>
> We are working through the details, I'll update this thread when I know
> more. Thanks for your patience :)
>
>
> Cheers
> Jan
> --
> >
> > On 26 November 2011 23:40, Noah Slater <ns...@tumbolia.org> wrote:
> >
> >> Cool idea.
> >>
> >> Just to re-iterate, we should keep things as simple as possible for
> now. I
> >> think we can get away with maintaining a set of easy to read, easy to
> edit
> >> HTML files that are served up along with Futon. These would be kept in
> the
> >> source exactly the the current set of HTML files that make up Futon
> are. We
> >> might want to create a /_docs URL handler, but we can get to that later.
> >>
> >> I have created a wiki page:
> >>
> >> http://wiki.apache.org/couchdb/SourceDocumentation
> >>
> >>
> >> I suggest that we start collecting a proposed table of contents here, or
> >> even the actual documentation. Once we have enough to work with, I plan
> on
> >> moving it in to the source, and hooking up all the relevant parts of the
> >> system. Then, when all that is done, we can re-visit how we're going to
> >> publish this on the web, and whether or how we tie that to our release
> >> procedure.
> >>
> >> First things first, let's get the documentation written down, and
> collected
> >> together before we continue.
> >>
> >> I suspect a lot of it may already exist on the wiki in one form or
> another,
> >> in which case, it should be good enough to just create a section for it
> as
> >> it will appear in the final documentation, and then include a reference
> to
> >> where it can be found on the wiki. Once we migrate the documentation
> over
> >> to its final home, we can go about resolving these references and
> cleaning
> >> things up.
> >>
> >>
> >> On Sat, Nov 26, 2011 at 11:14 PM, Randall Leeds <
> randall.leeds@gmail.com
> >>> wrote:
> >>
> >>> On Sat, Nov 26, 2011 at 14:42, Dale Harvey <da...@arandomurl.com>
> wrote:
> >>>> I will happily volunteer to work on generating html output from
> >> whatever
> >>> we
> >>>> store the documentation in, ultimately I think they should be
> >> integrated
> >>>> into futon, and I would request that whatever the documentation is
> >> stored
> >>>> in, that its its reasonably easy to parse and wrangle into your own
> >>> output *
> >>>>
> >>>
> >>> You bring up an amazing point. However we ship the documentation in
> >>> the source, it'd be cool to install it at /_docs or something. This
> >>> would be straightforward. It'd be easy for futon to embed that (but it
> >>> wouldn't be tied to futon). I'd love if the startup message had a link
> >>> to the "Getting Started" guide or something. That makes it a lot
> >>> friendlier for someone to browse the docs after installing CouchDB on
> >>> a remote server.
> >>>
> >>> -Randall
> >>>
> >>>> Also volunteer to do any work on the website needing done
> >>>>
> >>>> Cheers
> >>>> Dale
> >>>>
> >>>> * I am currently wrestling with the otp team changing the erlang
> >>>> documentation format every release and breaking erldocs
> >>>>
> >>>> On 26 November 2011 22:20, Randall Leeds <ra...@gmail.com>
> >>> wrote:
> >>>>
> >>>>> On Sat, Nov 26, 2011 at 11:41, Noah Slater <ns...@tumbolia.org>
> >>> wrote:
> >>>>>> That sounds reasonable. The sort of thing you'd get in an appendix,
> >> if
> >>>>> this
> >>>>>> were a book. A blow by blow description of each CouchDB feature,
> >>> config
> >>>>>> variable, URL parameter, etc.
> >>>>>>
> >>>>>> Seeding the wiki is a problem. The documentation should live in one
> >>>>> place,
> >>>>>> and one place only. Seeding the wiki is a one time process, but both
> >>> the
> >>>>>> docs we are discussing and the wiki are living documents. It is too
> >>> hard
> >>>>> to
> >>>>>> keep this kind of duplication up to date, and I will go out on a
> >> limb
> >>> and
> >>>>>> say that, eventually, the disparities will cause the docs to do more
> >>> harm
> >>>>>> than good.
> >>>>>>
> >>>>>> What I'd like to propose is that we make the docs we have in the
> >>> source
> >>>>>> directly accessible on the web.
> >>>>>
> >>>>> Absolutely. The main reason I want to see docs live in the source is
> >>>>> so that it's easy to tie a version of the docs to a release of the
> >>>>> source. That way, we can look at hosting a documentation site that
> has
> >>>>> docs for each version of CouchDB. See http://nodejs.org/docs/
> >>>>>
> >>>>>>
> >>>>>> How do we do that?
> >>>>>>
> >>>>>> The current CouchDB site is held in Subversion, and there is ASF
> >>>>>> infrastructure that mirrors this to a public location. Could we get
> >>>>>> something similar set up to host the contents of a specific folder
> >>> held
> >>>>> in
> >>>>>> Git? I don't know, but it's worth investigating.
> >>>>>>
> >>>>>> The only other option would be to host out of Git, like this:
> >>>>>>
> >>>>>>
> >>>>>
> >>>
> >>
> http://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob_plain;hb=HEAD;f=README
> >>>>>>
> >>>>>
> >>>>> FWIW I wouldn't mind adding a step to the release procedure to export
> >>>>> the docs @ some tag and push them up to the SVN site in a new folder.
> >>>>> It's not the most automatic and elegant thing in the world, but it's
> >>>>> simple and works today.
> >>>>>
> >>>>> Randall
> >>>>>
> >>>>
> >>>
> >>
>
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Jan Lehnardt <ja...@apache.org>.
On Nov 27, 2011, at 13:10 , Marco Monteiro wrote:
> I was under the impression that CouchBase might be available to give their
> (docbook) documentation to the project so that it can be used as the
> starting point. This would spare the community a lot of the work.
>
> Jan, is this still possible, and can it be worked out so that the
> documentation
> is in couchdb repo before, lets say, the end of the year?
We are working through the details, I'll update this thread when I know
more. Thanks for your patience :)
Cheers
Jan
--
>
> On 26 November 2011 23:40, Noah Slater <ns...@tumbolia.org> wrote:
>
>> Cool idea.
>>
>> Just to re-iterate, we should keep things as simple as possible for now. I
>> think we can get away with maintaining a set of easy to read, easy to edit
>> HTML files that are served up along with Futon. These would be kept in the
>> source exactly the the current set of HTML files that make up Futon are. We
>> might want to create a /_docs URL handler, but we can get to that later.
>>
>> I have created a wiki page:
>>
>> http://wiki.apache.org/couchdb/SourceDocumentation
>>
>>
>> I suggest that we start collecting a proposed table of contents here, or
>> even the actual documentation. Once we have enough to work with, I plan on
>> moving it in to the source, and hooking up all the relevant parts of the
>> system. Then, when all that is done, we can re-visit how we're going to
>> publish this on the web, and whether or how we tie that to our release
>> procedure.
>>
>> First things first, let's get the documentation written down, and collected
>> together before we continue.
>>
>> I suspect a lot of it may already exist on the wiki in one form or another,
>> in which case, it should be good enough to just create a section for it as
>> it will appear in the final documentation, and then include a reference to
>> where it can be found on the wiki. Once we migrate the documentation over
>> to its final home, we can go about resolving these references and cleaning
>> things up.
>>
>>
>> On Sat, Nov 26, 2011 at 11:14 PM, Randall Leeds <randall.leeds@gmail.com
>>> wrote:
>>
>>> On Sat, Nov 26, 2011 at 14:42, Dale Harvey <da...@arandomurl.com> wrote:
>>>> I will happily volunteer to work on generating html output from
>> whatever
>>> we
>>>> store the documentation in, ultimately I think they should be
>> integrated
>>>> into futon, and I would request that whatever the documentation is
>> stored
>>>> in, that its its reasonably easy to parse and wrangle into your own
>>> output *
>>>>
>>>
>>> You bring up an amazing point. However we ship the documentation in
>>> the source, it'd be cool to install it at /_docs or something. This
>>> would be straightforward. It'd be easy for futon to embed that (but it
>>> wouldn't be tied to futon). I'd love if the startup message had a link
>>> to the "Getting Started" guide or something. That makes it a lot
>>> friendlier for someone to browse the docs after installing CouchDB on
>>> a remote server.
>>>
>>> -Randall
>>>
>>>> Also volunteer to do any work on the website needing done
>>>>
>>>> Cheers
>>>> Dale
>>>>
>>>> * I am currently wrestling with the otp team changing the erlang
>>>> documentation format every release and breaking erldocs
>>>>
>>>> On 26 November 2011 22:20, Randall Leeds <ra...@gmail.com>
>>> wrote:
>>>>
>>>>> On Sat, Nov 26, 2011 at 11:41, Noah Slater <ns...@tumbolia.org>
>>> wrote:
>>>>>> That sounds reasonable. The sort of thing you'd get in an appendix,
>> if
>>>>> this
>>>>>> were a book. A blow by blow description of each CouchDB feature,
>>> config
>>>>>> variable, URL parameter, etc.
>>>>>>
>>>>>> Seeding the wiki is a problem. The documentation should live in one
>>>>> place,
>>>>>> and one place only. Seeding the wiki is a one time process, but both
>>> the
>>>>>> docs we are discussing and the wiki are living documents. It is too
>>> hard
>>>>> to
>>>>>> keep this kind of duplication up to date, and I will go out on a
>> limb
>>> and
>>>>>> say that, eventually, the disparities will cause the docs to do more
>>> harm
>>>>>> than good.
>>>>>>
>>>>>> What I'd like to propose is that we make the docs we have in the
>>> source
>>>>>> directly accessible on the web.
>>>>>
>>>>> Absolutely. The main reason I want to see docs live in the source is
>>>>> so that it's easy to tie a version of the docs to a release of the
>>>>> source. That way, we can look at hosting a documentation site that has
>>>>> docs for each version of CouchDB. See http://nodejs.org/docs/
>>>>>
>>>>>>
>>>>>> How do we do that?
>>>>>>
>>>>>> The current CouchDB site is held in Subversion, and there is ASF
>>>>>> infrastructure that mirrors this to a public location. Could we get
>>>>>> something similar set up to host the contents of a specific folder
>>> held
>>>>> in
>>>>>> Git? I don't know, but it's worth investigating.
>>>>>>
>>>>>> The only other option would be to host out of Git, like this:
>>>>>>
>>>>>>
>>>>>
>>>
>> http://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob_plain;hb=HEAD;f=README
>>>>>>
>>>>>
>>>>> FWIW I wouldn't mind adding a step to the release procedure to export
>>>>> the docs @ some tag and push them up to the SVN site in a new folder.
>>>>> It's not the most automatic and elegant thing in the world, but it's
>>>>> simple and works today.
>>>>>
>>>>> Randall
>>>>>
>>>>
>>>
>>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Marco Monteiro <ma...@textovirtual.com>.
I was under the impression that CouchBase might be available to give their
(docbook) documentation to the project so that it can be used as the
starting point. This would spare the community a lot of the work.
Jan, is this still possible, and can it be worked out so that the
documentation
is in couchdb repo before, lets say, the end of the year?
On 26 November 2011 23:40, Noah Slater <ns...@tumbolia.org> wrote:
> Cool idea.
>
> Just to re-iterate, we should keep things as simple as possible for now. I
> think we can get away with maintaining a set of easy to read, easy to edit
> HTML files that are served up along with Futon. These would be kept in the
> source exactly the the current set of HTML files that make up Futon are. We
> might want to create a /_docs URL handler, but we can get to that later.
>
> I have created a wiki page:
>
> http://wiki.apache.org/couchdb/SourceDocumentation
>
>
> I suggest that we start collecting a proposed table of contents here, or
> even the actual documentation. Once we have enough to work with, I plan on
> moving it in to the source, and hooking up all the relevant parts of the
> system. Then, when all that is done, we can re-visit how we're going to
> publish this on the web, and whether or how we tie that to our release
> procedure.
>
> First things first, let's get the documentation written down, and collected
> together before we continue.
>
> I suspect a lot of it may already exist on the wiki in one form or another,
> in which case, it should be good enough to just create a section for it as
> it will appear in the final documentation, and then include a reference to
> where it can be found on the wiki. Once we migrate the documentation over
> to its final home, we can go about resolving these references and cleaning
> things up.
>
>
> On Sat, Nov 26, 2011 at 11:14 PM, Randall Leeds <randall.leeds@gmail.com
> >wrote:
>
> > On Sat, Nov 26, 2011 at 14:42, Dale Harvey <da...@arandomurl.com> wrote:
> > > I will happily volunteer to work on generating html output from
> whatever
> > we
> > > store the documentation in, ultimately I think they should be
> integrated
> > > into futon, and I would request that whatever the documentation is
> stored
> > > in, that its its reasonably easy to parse and wrangle into your own
> > output *
> > >
> >
> > You bring up an amazing point. However we ship the documentation in
> > the source, it'd be cool to install it at /_docs or something. This
> > would be straightforward. It'd be easy for futon to embed that (but it
> > wouldn't be tied to futon). I'd love if the startup message had a link
> > to the "Getting Started" guide or something. That makes it a lot
> > friendlier for someone to browse the docs after installing CouchDB on
> > a remote server.
> >
> > -Randall
> >
> > > Also volunteer to do any work on the website needing done
> > >
> > > Cheers
> > > Dale
> > >
> > > * I am currently wrestling with the otp team changing the erlang
> > > documentation format every release and breaking erldocs
> > >
> > > On 26 November 2011 22:20, Randall Leeds <ra...@gmail.com>
> > wrote:
> > >
> > >> On Sat, Nov 26, 2011 at 11:41, Noah Slater <ns...@tumbolia.org>
> > wrote:
> > >> > That sounds reasonable. The sort of thing you'd get in an appendix,
> if
> > >> this
> > >> > were a book. A blow by blow description of each CouchDB feature,
> > config
> > >> > variable, URL parameter, etc.
> > >> >
> > >> > Seeding the wiki is a problem. The documentation should live in one
> > >> place,
> > >> > and one place only. Seeding the wiki is a one time process, but both
> > the
> > >> > docs we are discussing and the wiki are living documents. It is too
> > hard
> > >> to
> > >> > keep this kind of duplication up to date, and I will go out on a
> limb
> > and
> > >> > say that, eventually, the disparities will cause the docs to do more
> > harm
> > >> > than good.
> > >> >
> > >> > What I'd like to propose is that we make the docs we have in the
> > source
> > >> > directly accessible on the web.
> > >>
> > >> Absolutely. The main reason I want to see docs live in the source is
> > >> so that it's easy to tie a version of the docs to a release of the
> > >> source. That way, we can look at hosting a documentation site that has
> > >> docs for each version of CouchDB. See http://nodejs.org/docs/
> > >>
> > >> >
> > >> > How do we do that?
> > >> >
> > >> > The current CouchDB site is held in Subversion, and there is ASF
> > >> > infrastructure that mirrors this to a public location. Could we get
> > >> > something similar set up to host the contents of a specific folder
> > held
> > >> in
> > >> > Git? I don't know, but it's worth investigating.
> > >> >
> > >> > The only other option would be to host out of Git, like this:
> > >> >
> > >> >
> > >>
> >
> http://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob_plain;hb=HEAD;f=README
> > >> >
> > >>
> > >> FWIW I wouldn't mind adding a step to the release procedure to export
> > >> the docs @ some tag and push them up to the SVN site in a new folder.
> > >> It's not the most automatic and elegant thing in the world, but it's
> > >> simple and works today.
> > >>
> > >> Randall
> > >>
> > >
> >
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Robert Newson <rn...@apache.org>.
Noah: That one is on Jan.
On 26 November 2011 23:45, Noah Slater <ns...@tumbolia.org> wrote:
> Also, Bob, you mention Couchbase stepped in to fill this gap.
>
> Do you know where we can see the fruits of that labour? If licensing
> permits, we might find it useful to take that as a starting point, or at
> least reference the sections there as we can reference parts of the
> existing wiki, while compiling this stuff.
>
> On Sat, Nov 26, 2011 at 11:40 PM, Noah Slater <ns...@tumbolia.org> wrote:
>
>> Cool idea.
>>
>> Just to re-iterate, we should keep things as simple as possible for now. I
>> think we can get away with maintaining a set of easy to read, easy to edit
>> HTML files that are served up along with Futon. These would be kept in the
>> source exactly the the current set of HTML files that make up Futon are. We
>> might want to create a /_docs URL handler, but we can get to that later.
>>
>> I have created a wiki page:
>>
>> http://wiki.apache.org/couchdb/SourceDocumentation
>>
>>
>> I suggest that we start collecting a proposed table of contents here, or
>> even the actual documentation. Once we have enough to work with, I plan on
>> moving it in to the source, and hooking up all the relevant parts of the
>> system. Then, when all that is done, we can re-visit how we're going to
>> publish this on the web, and whether or how we tie that to our release
>> procedure.
>>
>> First things first, let's get the documentation written down, and
>> collected together before we continue.
>>
>> I suspect a lot of it may already exist on the wiki in one form or
>> another, in which case, it should be good enough to just create a section
>> for it as it will appear in the final documentation, and then include a
>> reference to where it can be found on the wiki. Once we migrate the
>> documentation over to its final home, we can go about resolving these
>> references and cleaning things up.
>>
>>
>> On Sat, Nov 26, 2011 at 11:14 PM, Randall Leeds <ra...@gmail.com>wrote:
>>
>>> On Sat, Nov 26, 2011 at 14:42, Dale Harvey <da...@arandomurl.com> wrote:
>>> > I will happily volunteer to work on generating html output from
>>> whatever we
>>> > store the documentation in, ultimately I think they should be integrated
>>> > into futon, and I would request that whatever the documentation is
>>> stored
>>> > in, that its its reasonably easy to parse and wrangle into your own
>>> output *
>>> >
>>>
>>> You bring up an amazing point. However we ship the documentation in
>>> the source, it'd be cool to install it at /_docs or something. This
>>> would be straightforward. It'd be easy for futon to embed that (but it
>>> wouldn't be tied to futon). I'd love if the startup message had a link
>>> to the "Getting Started" guide or something. That makes it a lot
>>> friendlier for someone to browse the docs after installing CouchDB on
>>> a remote server.
>>>
>>> -Randall
>>>
>>> > Also volunteer to do any work on the website needing done
>>> >
>>> > Cheers
>>> > Dale
>>> >
>>> > * I am currently wrestling with the otp team changing the erlang
>>> > documentation format every release and breaking erldocs
>>> >
>>> > On 26 November 2011 22:20, Randall Leeds <ra...@gmail.com>
>>> wrote:
>>> >
>>> >> On Sat, Nov 26, 2011 at 11:41, Noah Slater <ns...@tumbolia.org>
>>> wrote:
>>> >> > That sounds reasonable. The sort of thing you'd get in an appendix,
>>> if
>>> >> this
>>> >> > were a book. A blow by blow description of each CouchDB feature,
>>> config
>>> >> > variable, URL parameter, etc.
>>> >> >
>>> >> > Seeding the wiki is a problem. The documentation should live in one
>>> >> place,
>>> >> > and one place only. Seeding the wiki is a one time process, but both
>>> the
>>> >> > docs we are discussing and the wiki are living documents. It is too
>>> hard
>>> >> to
>>> >> > keep this kind of duplication up to date, and I will go out on a
>>> limb and
>>> >> > say that, eventually, the disparities will cause the docs to do more
>>> harm
>>> >> > than good.
>>> >> >
>>> >> > What I'd like to propose is that we make the docs we have in the
>>> source
>>> >> > directly accessible on the web.
>>> >>
>>> >> Absolutely. The main reason I want to see docs live in the source is
>>> >> so that it's easy to tie a version of the docs to a release of the
>>> >> source. That way, we can look at hosting a documentation site that has
>>> >> docs for each version of CouchDB. See http://nodejs.org/docs/
>>> >>
>>> >> >
>>> >> > How do we do that?
>>> >> >
>>> >> > The current CouchDB site is held in Subversion, and there is ASF
>>> >> > infrastructure that mirrors this to a public location. Could we get
>>> >> > something similar set up to host the contents of a specific folder
>>> held
>>> >> in
>>> >> > Git? I don't know, but it's worth investigating.
>>> >> >
>>> >> > The only other option would be to host out of Git, like this:
>>> >> >
>>> >> >
>>> >>
>>> http://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob_plain;hb=HEAD;f=README
>>> >> >
>>> >>
>>> >> FWIW I wouldn't mind adding a step to the release procedure to export
>>> >> the docs @ some tag and push them up to the SVN site in a new folder.
>>> >> It's not the most automatic and elegant thing in the world, but it's
>>> >> simple and works today.
>>> >>
>>> >> Randall
>>> >>
>>> >
>>>
>>
>>
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Noah Slater <ns...@tumbolia.org>.
Also, Bob, you mention Couchbase stepped in to fill this gap.
Do you know where we can see the fruits of that labour? If licensing
permits, we might find it useful to take that as a starting point, or at
least reference the sections there as we can reference parts of the
existing wiki, while compiling this stuff.
On Sat, Nov 26, 2011 at 11:40 PM, Noah Slater <ns...@tumbolia.org> wrote:
> Cool idea.
>
> Just to re-iterate, we should keep things as simple as possible for now. I
> think we can get away with maintaining a set of easy to read, easy to edit
> HTML files that are served up along with Futon. These would be kept in the
> source exactly the the current set of HTML files that make up Futon are. We
> might want to create a /_docs URL handler, but we can get to that later.
>
> I have created a wiki page:
>
> http://wiki.apache.org/couchdb/SourceDocumentation
>
>
> I suggest that we start collecting a proposed table of contents here, or
> even the actual documentation. Once we have enough to work with, I plan on
> moving it in to the source, and hooking up all the relevant parts of the
> system. Then, when all that is done, we can re-visit how we're going to
> publish this on the web, and whether or how we tie that to our release
> procedure.
>
> First things first, let's get the documentation written down, and
> collected together before we continue.
>
> I suspect a lot of it may already exist on the wiki in one form or
> another, in which case, it should be good enough to just create a section
> for it as it will appear in the final documentation, and then include a
> reference to where it can be found on the wiki. Once we migrate the
> documentation over to its final home, we can go about resolving these
> references and cleaning things up.
>
>
> On Sat, Nov 26, 2011 at 11:14 PM, Randall Leeds <ra...@gmail.com>wrote:
>
>> On Sat, Nov 26, 2011 at 14:42, Dale Harvey <da...@arandomurl.com> wrote:
>> > I will happily volunteer to work on generating html output from
>> whatever we
>> > store the documentation in, ultimately I think they should be integrated
>> > into futon, and I would request that whatever the documentation is
>> stored
>> > in, that its its reasonably easy to parse and wrangle into your own
>> output *
>> >
>>
>> You bring up an amazing point. However we ship the documentation in
>> the source, it'd be cool to install it at /_docs or something. This
>> would be straightforward. It'd be easy for futon to embed that (but it
>> wouldn't be tied to futon). I'd love if the startup message had a link
>> to the "Getting Started" guide or something. That makes it a lot
>> friendlier for someone to browse the docs after installing CouchDB on
>> a remote server.
>>
>> -Randall
>>
>> > Also volunteer to do any work on the website needing done
>> >
>> > Cheers
>> > Dale
>> >
>> > * I am currently wrestling with the otp team changing the erlang
>> > documentation format every release and breaking erldocs
>> >
>> > On 26 November 2011 22:20, Randall Leeds <ra...@gmail.com>
>> wrote:
>> >
>> >> On Sat, Nov 26, 2011 at 11:41, Noah Slater <ns...@tumbolia.org>
>> wrote:
>> >> > That sounds reasonable. The sort of thing you'd get in an appendix,
>> if
>> >> this
>> >> > were a book. A blow by blow description of each CouchDB feature,
>> config
>> >> > variable, URL parameter, etc.
>> >> >
>> >> > Seeding the wiki is a problem. The documentation should live in one
>> >> place,
>> >> > and one place only. Seeding the wiki is a one time process, but both
>> the
>> >> > docs we are discussing and the wiki are living documents. It is too
>> hard
>> >> to
>> >> > keep this kind of duplication up to date, and I will go out on a
>> limb and
>> >> > say that, eventually, the disparities will cause the docs to do more
>> harm
>> >> > than good.
>> >> >
>> >> > What I'd like to propose is that we make the docs we have in the
>> source
>> >> > directly accessible on the web.
>> >>
>> >> Absolutely. The main reason I want to see docs live in the source is
>> >> so that it's easy to tie a version of the docs to a release of the
>> >> source. That way, we can look at hosting a documentation site that has
>> >> docs for each version of CouchDB. See http://nodejs.org/docs/
>> >>
>> >> >
>> >> > How do we do that?
>> >> >
>> >> > The current CouchDB site is held in Subversion, and there is ASF
>> >> > infrastructure that mirrors this to a public location. Could we get
>> >> > something similar set up to host the contents of a specific folder
>> held
>> >> in
>> >> > Git? I don't know, but it's worth investigating.
>> >> >
>> >> > The only other option would be to host out of Git, like this:
>> >> >
>> >> >
>> >>
>> http://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob_plain;hb=HEAD;f=README
>> >> >
>> >>
>> >> FWIW I wouldn't mind adding a step to the release procedure to export
>> >> the docs @ some tag and push them up to the SVN site in a new folder.
>> >> It's not the most automatic and elegant thing in the world, but it's
>> >> simple and works today.
>> >>
>> >> Randall
>> >>
>> >
>>
>
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Noah Slater <ns...@tumbolia.org>.
Fair enough.
On Tue, Nov 29, 2011 at 12:49 AM, Randall Leeds <ra...@gmail.com>wrote:
> On Mon, Nov 28, 2011 at 15:09, Noah Slater <ns...@tumbolia.org> wrote:
> > Do you think stuff like coding standards, and conventions, might be
> better
> > documented on the wiki?
> >
>
> I don't have any problem with developer documentation in the source
> and installed documentation. For one, as we develop our plugin system
> some plugin developers may develop against couch using just the .hrl
> files from an installation. These plugins may want to increase their
> chance of going upstream by following the project coding conventions.
>
> > I was seeing this as more of an appendix style look-up for regular
> CouchDB
> > users.
> >
> > On Mon, Nov 28, 2011 at 8:24 PM, Joan Touzet <jo...@atypical.net> wrote:
> >
> >> On Sat, Nov 26, 2011 at 11:40:41PM +0000, Noah Slater wrote:
> >> > Cool idea.
> >>
> >> Agreed! As part of the coursework I'm planning for January, I can start
> >> contributing back class notes and information as well. This would be the
> >> start of documentation about how the code is laid out, formatting, etc.
> >> I see this as complementary, and whoever signs up for the course can
> >> also contribute at least 30-60 minutes of documentation cleanup as well.
> >>
> >> If the course is successful, as it is iterated, so too should new groups
> >> of students be available to help out as well. With any luck this will be
> >> self-sustaining.
> >>
> >> > I have created a wiki page:
> >> >
> >> > http://wiki.apache.org/couchdb/SourceDocumentation
> >>
> >> I'll add this to the wiki right now.
> >>
> >> -Joan
> >>
> >
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Randall Leeds <ra...@gmail.com>.
On Mon, Nov 28, 2011 at 15:09, Noah Slater <ns...@tumbolia.org> wrote:
> Do you think stuff like coding standards, and conventions, might be better
> documented on the wiki?
>
I don't have any problem with developer documentation in the source
and installed documentation. For one, as we develop our plugin system
some plugin developers may develop against couch using just the .hrl
files from an installation. These plugins may want to increase their
chance of going upstream by following the project coding conventions.
> I was seeing this as more of an appendix style look-up for regular CouchDB
> users.
>
> On Mon, Nov 28, 2011 at 8:24 PM, Joan Touzet <jo...@atypical.net> wrote:
>
>> On Sat, Nov 26, 2011 at 11:40:41PM +0000, Noah Slater wrote:
>> > Cool idea.
>>
>> Agreed! As part of the coursework I'm planning for January, I can start
>> contributing back class notes and information as well. This would be the
>> start of documentation about how the code is laid out, formatting, etc.
>> I see this as complementary, and whoever signs up for the course can
>> also contribute at least 30-60 minutes of documentation cleanup as well.
>>
>> If the course is successful, as it is iterated, so too should new groups
>> of students be available to help out as well. With any luck this will be
>> self-sustaining.
>>
>> > I have created a wiki page:
>> >
>> > http://wiki.apache.org/couchdb/SourceDocumentation
>>
>> I'll add this to the wiki right now.
>>
>> -Joan
>>
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Noah Slater <ns...@tumbolia.org>.
Do you think stuff like coding standards, and conventions, might be better
documented on the wiki?
I was seeing this as more of an appendix style look-up for regular CouchDB
users.
On Mon, Nov 28, 2011 at 8:24 PM, Joan Touzet <jo...@atypical.net> wrote:
> On Sat, Nov 26, 2011 at 11:40:41PM +0000, Noah Slater wrote:
> > Cool idea.
>
> Agreed! As part of the coursework I'm planning for January, I can start
> contributing back class notes and information as well. This would be the
> start of documentation about how the code is laid out, formatting, etc.
> I see this as complementary, and whoever signs up for the course can
> also contribute at least 30-60 minutes of documentation cleanup as well.
>
> If the course is successful, as it is iterated, so too should new groups
> of students be available to help out as well. With any luck this will be
> self-sustaining.
>
> > I have created a wiki page:
> >
> > http://wiki.apache.org/couchdb/SourceDocumentation
>
> I'll add this to the wiki right now.
>
> -Joan
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Joan Touzet <jo...@atypical.net>.
On Sat, Nov 26, 2011 at 11:40:41PM +0000, Noah Slater wrote:
> Cool idea.
Agreed! As part of the coursework I'm planning for January, I can start
contributing back class notes and information as well. This would be the
start of documentation about how the code is laid out, formatting, etc.
I see this as complementary, and whoever signs up for the course can
also contribute at least 30-60 minutes of documentation cleanup as well.
If the course is successful, as it is iterated, so too should new groups
of students be available to help out as well. With any luck this will be
self-sustaining.
> I have created a wiki page:
>
> http://wiki.apache.org/couchdb/SourceDocumentation
I'll add this to the wiki right now.
-Joan
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Noah Slater <ns...@tumbolia.org>.
Cool idea.
Just to re-iterate, we should keep things as simple as possible for now. I
think we can get away with maintaining a set of easy to read, easy to edit
HTML files that are served up along with Futon. These would be kept in the
source exactly the the current set of HTML files that make up Futon are. We
might want to create a /_docs URL handler, but we can get to that later.
I have created a wiki page:
http://wiki.apache.org/couchdb/SourceDocumentation
I suggest that we start collecting a proposed table of contents here, or
even the actual documentation. Once we have enough to work with, I plan on
moving it in to the source, and hooking up all the relevant parts of the
system. Then, when all that is done, we can re-visit how we're going to
publish this on the web, and whether or how we tie that to our release
procedure.
First things first, let's get the documentation written down, and collected
together before we continue.
I suspect a lot of it may already exist on the wiki in one form or another,
in which case, it should be good enough to just create a section for it as
it will appear in the final documentation, and then include a reference to
where it can be found on the wiki. Once we migrate the documentation over
to its final home, we can go about resolving these references and cleaning
things up.
On Sat, Nov 26, 2011 at 11:14 PM, Randall Leeds <ra...@gmail.com>wrote:
> On Sat, Nov 26, 2011 at 14:42, Dale Harvey <da...@arandomurl.com> wrote:
> > I will happily volunteer to work on generating html output from whatever
> we
> > store the documentation in, ultimately I think they should be integrated
> > into futon, and I would request that whatever the documentation is stored
> > in, that its its reasonably easy to parse and wrangle into your own
> output *
> >
>
> You bring up an amazing point. However we ship the documentation in
> the source, it'd be cool to install it at /_docs or something. This
> would be straightforward. It'd be easy for futon to embed that (but it
> wouldn't be tied to futon). I'd love if the startup message had a link
> to the "Getting Started" guide or something. That makes it a lot
> friendlier for someone to browse the docs after installing CouchDB on
> a remote server.
>
> -Randall
>
> > Also volunteer to do any work on the website needing done
> >
> > Cheers
> > Dale
> >
> > * I am currently wrestling with the otp team changing the erlang
> > documentation format every release and breaking erldocs
> >
> > On 26 November 2011 22:20, Randall Leeds <ra...@gmail.com>
> wrote:
> >
> >> On Sat, Nov 26, 2011 at 11:41, Noah Slater <ns...@tumbolia.org>
> wrote:
> >> > That sounds reasonable. The sort of thing you'd get in an appendix, if
> >> this
> >> > were a book. A blow by blow description of each CouchDB feature,
> config
> >> > variable, URL parameter, etc.
> >> >
> >> > Seeding the wiki is a problem. The documentation should live in one
> >> place,
> >> > and one place only. Seeding the wiki is a one time process, but both
> the
> >> > docs we are discussing and the wiki are living documents. It is too
> hard
> >> to
> >> > keep this kind of duplication up to date, and I will go out on a limb
> and
> >> > say that, eventually, the disparities will cause the docs to do more
> harm
> >> > than good.
> >> >
> >> > What I'd like to propose is that we make the docs we have in the
> source
> >> > directly accessible on the web.
> >>
> >> Absolutely. The main reason I want to see docs live in the source is
> >> so that it's easy to tie a version of the docs to a release of the
> >> source. That way, we can look at hosting a documentation site that has
> >> docs for each version of CouchDB. See http://nodejs.org/docs/
> >>
> >> >
> >> > How do we do that?
> >> >
> >> > The current CouchDB site is held in Subversion, and there is ASF
> >> > infrastructure that mirrors this to a public location. Could we get
> >> > something similar set up to host the contents of a specific folder
> held
> >> in
> >> > Git? I don't know, but it's worth investigating.
> >> >
> >> > The only other option would be to host out of Git, like this:
> >> >
> >> >
> >>
> http://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob_plain;hb=HEAD;f=README
> >> >
> >>
> >> FWIW I wouldn't mind adding a step to the release procedure to export
> >> the docs @ some tag and push them up to the SVN site in a new folder.
> >> It's not the most automatic and elegant thing in the world, but it's
> >> simple and works today.
> >>
> >> Randall
> >>
> >
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Randall Leeds <ra...@gmail.com>.
On Sat, Nov 26, 2011 at 14:42, Dale Harvey <da...@arandomurl.com> wrote:
> I will happily volunteer to work on generating html output from whatever we
> store the documentation in, ultimately I think they should be integrated
> into futon, and I would request that whatever the documentation is stored
> in, that its its reasonably easy to parse and wrangle into your own output *
>
You bring up an amazing point. However we ship the documentation in
the source, it'd be cool to install it at /_docs or something. This
would be straightforward. It'd be easy for futon to embed that (but it
wouldn't be tied to futon). I'd love if the startup message had a link
to the "Getting Started" guide or something. That makes it a lot
friendlier for someone to browse the docs after installing CouchDB on
a remote server.
-Randall
> Also volunteer to do any work on the website needing done
>
> Cheers
> Dale
>
> * I am currently wrestling with the otp team changing the erlang
> documentation format every release and breaking erldocs
>
> On 26 November 2011 22:20, Randall Leeds <ra...@gmail.com> wrote:
>
>> On Sat, Nov 26, 2011 at 11:41, Noah Slater <ns...@tumbolia.org> wrote:
>> > That sounds reasonable. The sort of thing you'd get in an appendix, if
>> this
>> > were a book. A blow by blow description of each CouchDB feature, config
>> > variable, URL parameter, etc.
>> >
>> > Seeding the wiki is a problem. The documentation should live in one
>> place,
>> > and one place only. Seeding the wiki is a one time process, but both the
>> > docs we are discussing and the wiki are living documents. It is too hard
>> to
>> > keep this kind of duplication up to date, and I will go out on a limb and
>> > say that, eventually, the disparities will cause the docs to do more harm
>> > than good.
>> >
>> > What I'd like to propose is that we make the docs we have in the source
>> > directly accessible on the web.
>>
>> Absolutely. The main reason I want to see docs live in the source is
>> so that it's easy to tie a version of the docs to a release of the
>> source. That way, we can look at hosting a documentation site that has
>> docs for each version of CouchDB. See http://nodejs.org/docs/
>>
>> >
>> > How do we do that?
>> >
>> > The current CouchDB site is held in Subversion, and there is ASF
>> > infrastructure that mirrors this to a public location. Could we get
>> > something similar set up to host the contents of a specific folder held
>> in
>> > Git? I don't know, but it's worth investigating.
>> >
>> > The only other option would be to host out of Git, like this:
>> >
>> >
>> http://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob_plain;hb=HEAD;f=README
>> >
>>
>> FWIW I wouldn't mind adding a step to the release procedure to export
>> the docs @ some tag and push them up to the SVN site in a new folder.
>> It's not the most automatic and elegant thing in the world, but it's
>> simple and works today.
>>
>> Randall
>>
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Dale Harvey <da...@arandomurl.com>.
I will happily volunteer to work on generating html output from whatever we
store the documentation in, ultimately I think they should be integrated
into futon, and I would request that whatever the documentation is stored
in, that its its reasonably easy to parse and wrangle into your own output *
Also volunteer to do any work on the website needing done
Cheers
Dale
* I am currently wrestling with the otp team changing the erlang
documentation format every release and breaking erldocs
On 26 November 2011 22:20, Randall Leeds <ra...@gmail.com> wrote:
> On Sat, Nov 26, 2011 at 11:41, Noah Slater <ns...@tumbolia.org> wrote:
> > That sounds reasonable. The sort of thing you'd get in an appendix, if
> this
> > were a book. A blow by blow description of each CouchDB feature, config
> > variable, URL parameter, etc.
> >
> > Seeding the wiki is a problem. The documentation should live in one
> place,
> > and one place only. Seeding the wiki is a one time process, but both the
> > docs we are discussing and the wiki are living documents. It is too hard
> to
> > keep this kind of duplication up to date, and I will go out on a limb and
> > say that, eventually, the disparities will cause the docs to do more harm
> > than good.
> >
> > What I'd like to propose is that we make the docs we have in the source
> > directly accessible on the web.
>
> Absolutely. The main reason I want to see docs live in the source is
> so that it's easy to tie a version of the docs to a release of the
> source. That way, we can look at hosting a documentation site that has
> docs for each version of CouchDB. See http://nodejs.org/docs/
>
> >
> > How do we do that?
> >
> > The current CouchDB site is held in Subversion, and there is ASF
> > infrastructure that mirrors this to a public location. Could we get
> > something similar set up to host the contents of a specific folder held
> in
> > Git? I don't know, but it's worth investigating.
> >
> > The only other option would be to host out of Git, like this:
> >
> >
> http://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob_plain;hb=HEAD;f=README
> >
>
> FWIW I wouldn't mind adding a step to the release procedure to export
> the docs @ some tag and push them up to the SVN site in a new folder.
> It's not the most automatic and elegant thing in the world, but it's
> simple and works today.
>
> Randall
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Randall Leeds <ra...@gmail.com>.
On Sat, Nov 26, 2011 at 11:41, Noah Slater <ns...@tumbolia.org> wrote:
> That sounds reasonable. The sort of thing you'd get in an appendix, if this
> were a book. A blow by blow description of each CouchDB feature, config
> variable, URL parameter, etc.
>
> Seeding the wiki is a problem. The documentation should live in one place,
> and one place only. Seeding the wiki is a one time process, but both the
> docs we are discussing and the wiki are living documents. It is too hard to
> keep this kind of duplication up to date, and I will go out on a limb and
> say that, eventually, the disparities will cause the docs to do more harm
> than good.
>
> What I'd like to propose is that we make the docs we have in the source
> directly accessible on the web.
Absolutely. The main reason I want to see docs live in the source is
so that it's easy to tie a version of the docs to a release of the
source. That way, we can look at hosting a documentation site that has
docs for each version of CouchDB. See http://nodejs.org/docs/
>
> How do we do that?
>
> The current CouchDB site is held in Subversion, and there is ASF
> infrastructure that mirrors this to a public location. Could we get
> something similar set up to host the contents of a specific folder held in
> Git? I don't know, but it's worth investigating.
>
> The only other option would be to host out of Git, like this:
>
> http://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob_plain;hb=HEAD;f=README
>
FWIW I wouldn't mind adding a step to the release procedure to export
the docs @ some tag and push them up to the SVN site in a new folder.
It's not the most automatic and elegant thing in the world, but it's
simple and works today.
Randall
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Noah Slater <ns...@tumbolia.org>.
That sounds reasonable. The sort of thing you'd get in an appendix, if this
were a book. A blow by blow description of each CouchDB feature, config
variable, URL parameter, etc.
Seeding the wiki is a problem. The documentation should live in one place,
and one place only. Seeding the wiki is a one time process, but both the
docs we are discussing and the wiki are living documents. It is too hard to
keep this kind of duplication up to date, and I will go out on a limb and
say that, eventually, the disparities will cause the docs to do more harm
than good.
What I'd like to propose is that we make the docs we have in the source
directly accessible on the web.
How do we do that?
The current CouchDB site is held in Subversion, and there is ASF
infrastructure that mirrors this to a public location. Could we get
something similar set up to host the contents of a specific folder held in
Git? I don't know, but it's worth investigating.
The only other option would be to host out of Git, like this:
http://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob_plain;hb=HEAD;f=README
The only problem being how links work. Relative links wont work properly,
because the filename is passed in as a query string parameter. Is there any
way around this that doesn't involve a proxy and a bit of mod_rewrite?
As for the use-case, this is an important question.
Is it important that this stuff be included in the source? There are two
reasons why this might be the case. Firstly, it allows people with only the
source (and no net connection) to read the documentation. It's not the
1980s anymore, so this doesn't really seem too important. Secondly, it lets
us enforce a policy of updating the docs as you update the features. This
one seems very important.
Is it important for this stuff to exist in multiple formats, or is HTML
just fine? If we used a document toolchain like DocBook or LaTeX, we get a
bunch of nice output options for PS, and PostScript, and Ghostscript, etc.
But seriously, who reads documentation like that anymore? Again, it's not
the 1980s anymore. I think that HTML is just fine. If you want a PDF, your
browser can do that.
And to this end (and if you're called Jan or J. Chris, you've already
pre-emptied me) I suggest we write our documentation in HTML. No toolchain,
no conversion, no transformation, no XML nonsense, no fuss. Just straight
up, simple, HTML.
We did this for the CouchDB book, and it works just fine:
https://github.com/oreilly/couchdb-guide/tree/gh-pages/draft
https://github.com/oreilly/couchdb-guide/blob/gh-pages/draft/why.html
If you find that hard to edit, then god help you, no amount
of intermediary format is going to help! ;)
On Sat, Nov 26, 2011 at 7:14 PM, Robert Newson <rn...@apache.org> wrote:
> For me, the goal would be for docs/ to contain at least a brief
> description of every couchdb feature. I specifically don't expect to
> see introductory text, example views, tutorials, etc, except where
> needed to describe core features. One thing we've missed for a long
> time, and Couchbase had to step in and fill this gap for us, is a
> genuinely comprehensive list of everything couchdb can do (all those
> funny corners like ?batch=ok, all_or_nothing, etc).
>
> I hope this answers your secondary questions, but I'd add that I'd
> expect to see the docs/ folder used to seed the wiki and other
> documentation efforts. It would become part of our procedure to insist
> that a commit that adds a feature also adds documentation for that
> feature (the way it ought to include verifying tests).
>
> B.
>
> On 26 November 2011 18:23, Noah Slater <ns...@tumbolia.org> wrote:
> > Let's forget about the format or the toolchain for now, they're
> bikesheds.
> >
> > What is the goal of this effort?
> >
> > We want documentation in the source, sure. But why? What kind of
> > documentation is it going to be? What topics will it cover? Can anyone
> come
> > up with a suggested outline for it? i.e. Table of Contents
> >
> > Secondly, who's going to be use it, and in what situation? Typical
> > use scenarios please!
> >
> > Thirdly, who's going to write it?
> >
> > Once we have that nailed down, we can move forward sensibly.
> >
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Robert Newson <rn...@apache.org>.
For me, the goal would be for docs/ to contain at least a brief
description of every couchdb feature. I specifically don't expect to
see introductory text, example views, tutorials, etc, except where
needed to describe core features. One thing we've missed for a long
time, and Couchbase had to step in and fill this gap for us, is a
genuinely comprehensive list of everything couchdb can do (all those
funny corners like ?batch=ok, all_or_nothing, etc).
I hope this answers your secondary questions, but I'd add that I'd
expect to see the docs/ folder used to seed the wiki and other
documentation efforts. It would become part of our procedure to insist
that a commit that adds a feature also adds documentation for that
feature (the way it ought to include verifying tests).
B.
On 26 November 2011 18:23, Noah Slater <ns...@tumbolia.org> wrote:
> Let's forget about the format or the toolchain for now, they're bikesheds.
>
> What is the goal of this effort?
>
> We want documentation in the source, sure. But why? What kind of
> documentation is it going to be? What topics will it cover? Can anyone come
> up with a suggested outline for it? i.e. Table of Contents
>
> Secondly, who's going to be use it, and in what situation? Typical
> use scenarios please!
>
> Thirdly, who's going to write it?
>
> Once we have that nailed down, we can move forward sensibly.
>
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Noah Slater <ns...@tumbolia.org>.
Let's forget about the format or the toolchain for now, they're bikesheds.
What is the goal of this effort?
We want documentation in the source, sure. But why? What kind of
documentation is it going to be? What topics will it cover? Can anyone come
up with a suggested outline for it? i.e. Table of Contents
Secondly, who's going to be use it, and in what situation? Typical
use scenarios please!
Thirdly, who's going to write it?
Once we have that nailed down, we can move forward sensibly.
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Dave Cottlehuber <da...@muse.net.nz>.
On 23 November 2011 09:30, Benoit Chesneau <bc...@gmail.com> wrote:
> On Tue, Nov 22, 2011 at 3:08 PM, Dave Cottlehuber <da...@muse.net.nz> wrote:
>
>> NB this is readable as markdown on https://gist.github.com/gists/1385728
>
> +1 for the idea.
Thanks for your support Benoit.
> I think we alreadt discussed about it but I see a lot of people going to
> rest in place of docbook. But I will rely on someone else to do the choice.
I assume this is a +0 form you in regard to the actual tool.
> 3 & 4 return 404 ;) . I'm -1 in all other layout. They aren't enough punchy
> imo.
Now that I've fixed 3 and 4, any additional thoughts?
kriesse [3]: https://github.com/Kriesse/couchdb_web or view at
http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/kriesse_couch_web/index.html
eegg [4]: https://github.com/eegg/couchdb_web or view at
http://skunkwerks.iriscouch.com/couchdocs/_design/couchdocs/eegg_couch_web/index.html
> - benoît
>
A+
Dave
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Randall Leeds <ra...@gmail.com>.
On Wed, Nov 23, 2011 at 03:33, Benoit Chesneau <bc...@gmail.com> wrote:
> On Wed, Nov 23, 2011 at 9:30 AM, Benoit Chesneau <bc...@gmail.com>wrote:
>
>>
>>
>> On Tue, Nov 22, 2011 at 3:08 PM, Dave Cottlehuber <da...@muse.net.nz>wrote:
>>
>>>
>>> 3 & 4 return 404 ;) . I'm -1 in all other layout. They aren't enough
>> punchy imo.
>>
>>
>> s/other layout/others layouts
>
> the design too but it's a matter of taste in this case. I'm
> more interested by the layout . I like the cassandra layout for example :
>
> http://cassandra.apache.org/
>
> top menu i simple. and quickly introduce to main concepts.
>
> - benoît
>
Yes. It is decent. Action to download on the right is clear and pulls
the eye. I don't like the tabs, though (Welcome, Video, Slides).
Moving parts are less accessible, maybe.
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Benoit Chesneau <bc...@gmail.com>.
On Wed, Nov 23, 2011 at 9:30 AM, Benoit Chesneau <bc...@gmail.com>wrote:
>
>
> On Tue, Nov 22, 2011 at 3:08 PM, Dave Cottlehuber <da...@muse.net.nz>wrote:
>
>>
>> 3 & 4 return 404 ;) . I'm -1 in all other layout. They aren't enough
> punchy imo.
>
>
> s/other layout/others layouts
the design too but it's a matter of taste in this case. I'm
more interested by the layout . I like the cassandra layout for example :
http://cassandra.apache.org/
top menu i simple. and quickly introduce to main concepts.
- benoît
Re: [VOTE] Apache CouchDB new docs proposal
Posted by Benoit Chesneau <bc...@gmail.com>.
On Tue, Nov 22, 2011 at 3:08 PM, Dave Cottlehuber <da...@muse.net.nz> wrote:
> Hi devs,
>
> Over the last two years we've discussed improving our documentation,
> website,
> and wiki. We have discussed several designs ad mortem[1]…[5], and while the
> wiki has evolved substantially, not much else has changed.
>
> This proposal summarises a consensus direction, and puts forward an
> approach
> that should allow us to improve docs in incremental stages with the usual
> peer review process for the actual patches/changes.
>
> NB this is readable as markdown on https://gist.github.com/gists/1385728
>
> # Apache CouchDB Docs Spruce-Up
>
> CouchDB's documentation (wiki, API docs, and website) reflects its rapid
> evolution. We need a spruce up!
>
> The plan is:
>
> - nominate a PMC owner (nslater)
> - update the website (dch)
> - tidy up the wiki (anybody?)
> - implement docbook for APIs etc
>
> ## Update the CouchDB.org[0] website
>
> "The design is less important than the content." J Chris Anderson
>
> Previous work has stopped at the design stage, rather than getting the
> content.
>
> ### Phase 1
> - select one of the previously worked designs[0]..[5] and migrate current
> content into it
>
> ### Phase 2
>
> - review all pages and update as needed
> - make it easy to navigate to key content (even if not in same site)
> - overview, use case & philosophy
> - source, roadmap
> - API docs, wiki
> - mailing lists/archives
> - community contributions incl tools & tutorials, blogs, stories,
> binaries
> - links to hosting & commercial support
>
> ### Phase 3
> - check if any of the commercial vendors would be willing to fund a
> designer
>
> ## Tidy up the wiki
> - add a page which lists all pages
> - ask people to own reviewing each page
> - get writing/restructuring/pruning
>
> ## Implement DocBook
> - jan to clarify what's available from CouchBase
> - nslater to look at implementing this, or failing that something else
> - ask community for ideas for overall chapter structure
> - get an owner for each chapter + solicit contributions from community
> - get writing ...
> - develop guidelines a la existing Release Procedure for doc contributions
> to patches, releases, and commits
>
> I would like to call a vote[6],[7] for the above proposal. Feel free to
> read the existing emails on this subject [8][9][10].
>
> We encourage the whole community to review and give feedback -- everyone is
> free to vote on this proposal, so get stuck in!
>
> Happy voting,
> Dave Cottlehuber
> https://github.com/dch
>
> "Can we just commit this and work on any remaining details that
> someone wants to put in effort to fix?"
>
> "I think a big part of Rails' early success was the website:
> http://rubyonrails.org/"
>
> "The design is less important than the content."
>
> "Having all the blog posts, wikis, videos, case-studies, IRC logs,
> screen-casts, etc. available in a an easy-to-digest website, will make
> no-hassle for newcomers, which is the most important thing."
>
> "make it easy for new arrivals to find just what they need to know about
> CouchDB, while at the same time giving them a taste of the "Relax"
> feeling."
>
> ## references
>
> - current [0]: http://www.couchdb.org/
> - classic [1]:
> http://people.apache.org/~jan/couchdb.org.new/couch-classic/htdocs/
> - minimal [2]:
> http://people.apache.org/~jan/couchdb.org.new/couch-site/htdocs/
> - kriesse [3]: https://github.com/Kriesse/couchdb_web or view at
>
> https://www.dropbox.com/s/oq0bd9w7ufb0a3b/CouchDB/tmp/new_websites/kriesse/index.html
> - eegg [4]: https://github.com/eegg/couchdb_web or view at
>
> https://www.dropbox.com/s/oq0bd9w7ufb0a3b/CouchDB/tmp/new_websites/eegg/index.html
> - lean [5]: http://jan.prima.de/couchdb_web/
>
> - voting: [6]: http://www.apache.org/foundation/voting.html
> - release: [7]: http://wiki.apache.org/couchdb/Release_procedure
>
> - website [8]: http://bit.ly/rTt0kV
> - wiki [9]: http://bit.ly/vJDITc
> - docs [10]: http://bit.ly/ufasCB
>
+1 for the idea.
I think we alreadt discussed about it but I see a lot of people going to
rest in place of docbook. But I will rely on someone else to do the choice.
3 & 4 return 404 ;) . I'm -1 in all other layout. They aren't enough punchy
imo.
- benoît