couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Cottlehuber <>
Subject [VOTE] Apache CouchDB new docs proposal
Date Tue, 22 Nov 2011 14:08:35 GMT
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

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

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

"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]:
- classic  [1]:
- minimal  [2]:
- kriesse  [3]: or view at
- eegg     [4]: or view at
- lean     [5]:

- voting:  [6]:
- release: [7]:

- website  [8]:
- wiki     [9]:
- docs     [10]:

View raw message