+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 <d...@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 >
