couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Cottlehuber <d...@muse.net.nz>
Subject Re: Docs, second try
Date Wed, 01 Aug 2012 11:11:43 GMT
snip, hopefully a summary.

Situation:
Our docs are sucky, fragmented and what there is needs some attention
(wiki, couchbase, guide).
Couchbase has kindly donated DocBook[1] format API docs, and the tools
to manage that. Woot!
We don't have a clear understanding of what we are trying to produce
as an end result.

In order of importance:

1. docbook format is a *perceived* barrier to contribution.
After Dale prodded me I got it working properly & am adding notes[2] on adding:
- chapters (separate file)
- lists
- code sections
- references (incl cross chapter)
- tables

DocBook is *very* wordy but any decent editor with <>/ tab completion,
or zen coding will work.
It's trivial to convert snippets of other formats back to DocBook
using pandoc[3] or your tool of choice.
Would using DB *stop* any of the committers?

2. A clear list of output formats, and desired doc functionality is
required before bikeshedding on tools. I think this list is:

2.1 MUST output to HTML to embed in the source, and onto couchdb.apache.org site
2.2 MUST support chapters, sections, lists (numbered & normal), url
refs (html links), code blocks, images, and tables
2.3 OPTIONAL syntax highlighting of code & JSON
Markdown doesn't properly support 2.2.
RST & DocBook do.
RST does provide 2.3 syntax highlighting from what I can see. DocBook
probably could too but it's not obvious how.

3. Who's doing the work & where?

3.1 enabling community contribution is a MUST, in fact THE MUST DO TOP PRIORITY.
3.2 the community SHOULD easily be able to edit docs on github or
their own git fork easily
3.3 The bulk of documentation changes is going to be done by
committers over time
3.4 the toolchain should be integratable into a normal make
checks/make dist cycle on our supported platforms.

- markdown and .rst are supported on github in some form, which I
think is really important for facilitating easy community
contributions
- there is a clear preference to using .rst in the python dev
community, and the tooling appears simpler
- docbook can do anything** if you have the time & expertise.
- since my export to rst last night, we have already 3 beautiful
examples of how rst can simplify getting stuff done:
    - editing (assuming you have repo access)
https://github.com/djco/couchdb/blob/docs/share/docs/sphinx-docs/intro.rst
    - reading via sphinx & read the docs:
http://couchdb.readthedocs.org/en/latest/replication.html
    - embedded as a couch "app" http://kxepal.iriscouch.com/docs/1.1/index.html

TL;DR:
the only major objections against DocBook are:
- syntax is wordy but manageable
- toolchain is not perfect

But overall, .rst is the way to go, because:
- we'll end up with more documentation as a result
- good community engagement for tooling & using it
- it seems to meet the functional requirements
- it can be set up as a github repo to enable a wider pool of folk to contribute
- AFAICT if reqd it could roundtrip to DocBook if needed

Either way, whether in XML or RST I have enough bits to do what I was
planning to do. Thanks Jan & Noah & others who got us to this point
(I'll graciously overlook him mentioning texinfo and postscript).

Do we have a concensus now to go for RST & python nirvana?

[1]: http://wiki.apache.org/couchdb/Documentation
[2]: https://github.com/dch/couchdb/tree/docs/share/docs/
[3]: http://johnmacfarlane.net/pandoc/try

Mime
View raw message