Skip to content

Instantly share code, notes, and snippets.

@dch

dch/couchdocs_refresh.md

Created November 22, 2011 14:04
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save dch/1385728 to your computer and use it in GitHub Desktop.
Save dch/1385728 to your computer and use it in GitHub Desktop.
Download ZIP
CouchDB Doc Refresh
Raw
couchdocs_refresh.md

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment