API documentation

[mfenniak]

Write API documentation mirroring the RethinkDB docs (http://www.rethinkdb.com/api/) but for this client.

[HorizonNet]

Is someone already working on this one? If not, where should it be placed?

[mfenniak]

Nobody has worked on this yet, but it would be awesome if you're interested in it. My first thought for where to place documentation would be to use a service like Read the Docs (https://readthedocs.org/), which can pull a Sphinx documentation project out of a git tree and host it. I'm not sure if there are any other, similar services out there... I'd be open to suggestions. RTD's approach definitely skews towards Python projects, but I don't think it would hamper documenting a C# project very much.

Another approach would be just using a wiki, like the GitHub one attached to the project. But that's a fairly primitive approach; no version control, limited text search, and a different collaboration model (edit-in-place, rather than forks and pull-requests).

[HorizonNet]

I'm definitely interested in doing it. Let me do some research about possible solutions and after that I will post some suggestions.

[HorizonNet]

What about GitHub Pages? With that we have version control. The page would reside in its own branch and changes can be published to this branch.

[mfenniak]

I don't mind GitHub Pages as a hosting solution. It still leaves open the question of how to manage the content on those pages though. :-)

[HorizonNet]

The content can be created in either HTML or Markdown. The layout for the site would be HTML. If we choose to use Markdown for creating the content (which I would prefer) the engine behind GitHub Pages (Jekyll) will translate it into HTML. I have played around with it a little bit and it works very well. You can also create your own layout for the whole site to let it look more like the one of the official site.

The content would reside in its own branch (gh-pages) in this project. The documentation would be committed to this branch and has to go through the same PR process as any other commit. I would suggest that the structure is similar to the official documentation (the link you provided above). The content itself would be in one index.md file in the root of this branch. Later, when the documentation grows, we can decide to split it up in several files.

We start by adding the first features mentioned in the documentation and the rest will be added step by step. If something in one of these features changes in the future we just have to make a PR to the gh-pages branch and the documentation will be up-to-date immediately.

If you prefer an automated approach, a documentation tool can also be used. If it supports HTML (or Markdown) as an output format (such as the Sphinx HTML builder) this output can be committed to the documentation branch. It is then automatically on the documentation page.

[mfenniak]

I think using Jekyll and GitHub Pages sounds like a fine approach. If you want to put together the initial gh-pages branch, then I'll merge it into this repo whenever it has some initial content. I'd be happy to add you as a repo collaborator after that first merge.

[HorizonNet]

Sounds good to me. The only thing I need is a blank gh-pages branch to which I can make the PR from my fork against.

I'm on the road for some time now, but I hope I can create some initial content during the coming weeks.

[mfenniak]

I've created an initial gh-pages branch. It has a stub index.html file; couldn't figure out how to do the initial commit completely empty.

[HorizonNet]

Looks good. I will do the rest.