The Cloudant docs look great. Nicely done :). The main question for me is how we get the docs translated in the easiest way. Is that done with these docs already? If not, are there ideas how to do it?
Actually I see both advantages and disadvantages with rst. Basically I don't care in which way I have to write the docs. rst is a bit more complicated and ugly but offers many possibilities. MD is dead simple (I write nearly everything in MD!) but is a bit limited. At the end I would definitely prefer to use MD. Hosting the docs externally has been done, because there was no own infra - as Alex stated. But nothing is against hosting it by ourselves I think. My biggest concern is how we can translate the docs in the most easy way. As you may remember I outlined very much about this ticket but till today we have not been able (due to lack of time) to get the docs translated. The tool we use (pootle at translate.apache.org) is working good. We just need the process to reimport the translated docs into the CouchDB documentation. Please remember also, that there been done a quite good amount of translation work already. We should find a way to not throw away this work. And we should keep the most important things like * searchable * crossreferencing * code examples (done!) * easy usage If that is possible, I am +1 on switching. Cheers Andy On 28 October 2014 08:31, Alexander Shorin <[email protected]> wrote: > On Tue, Oct 28, 2014 at 12:52 AM, Joan Touzet <[email protected]> wrote: > > * Self-hosted documentation. Why aren't we doing this yet? > > Sphinx docs could be hosted on CouchDB - I always did that to provide > review examples. We're not doing this because we don't have own > CouchDB server on couchdb.apache.org - the only was from IrisCouch, > but those is dead now. Current position against self-hosting on > CouchDB was shaped in form "RTD doing this fine and we don't need to > care about hosting problems. KISS.". To change this, we need 1) > CouchDB host 2) couchapp tool 3) small script to fix underscore names > in output static html build - problem solved. > > > * Built-in examples in many languages. Yum! > > The problem I see with slate is that examples aren't useful in context > to show how CouchDB API really works since there are no complete > request/response descriptions, only payload data. Headers matters, you > know, as like as exact output format since CouchDB loves line-based > protocols. Since CouchDB API is HTTP-driven, it should be described in > HTTP examples. How use it via language X is a question of more high > level description. > > Also: > How do you plan to test these examples to be sure that they are even > works and all does the same things? Plain HTTP request/response > hardly, but possible; multiple languages examples will require to > setup quite more complex environment. > > Which CouchDB clients will you recommend to work with CouchDB through > these examples and why these? Currently, we are quite neutral in > question of tools for working with CouchDB, but I don't think we > should show how to make requests to CouchDB using Python's builtin > urllib. > > > * Markdown driven (if you <3 .md) > > Markdown is not documentation markup. It's used for HTML generation > and was invented for solving this problem unlike reStructured Text. > We'd discussed md vs rst on the very first days when Couchbase docs > get to be imported - it's easy to start with markdown, but it's not > possible to move forward with (localization, indexing, > crossreferences, version tags, glossary, search, customization and > more and more). > > P.S. Bug report: current layout looks awesome on 22' monitor, but > tables are completely broken for 13' one. > > -- > ,,,^..^,,, > -- Andy Wenk Hamburg - Germany RockIt! GPG fingerprint: C044 8322 9E12 1483 4FEC 9452 B65D 6BE3 9ED3 9588 https://people.apache.org/keys/committer/andywenk.asc
