couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Randall Leeds <randall.le...@gmail.com>
Subject Re: [VOTE] Apache CouchDB new docs proposal
Date Wed, 23 Nov 2011 08:10:38 GMT
+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 <dave@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
>

Mime
View raw message