[zeromq-dev] Documentation Proposal

[Peter Alexander]

Abstract
=======

This thread is to introduce for discussion, a documentation overhaul.
Please speak up and add your input. Watch this thread for follow up
posts that will drill down in detail as we go forward.

Status Quo
=========

In stead of ticking of all the aspects, I think we can agree that
currently, there is serious disarray. Lets just say that if you can
think of a needed change / expansion / consolidation, I have already
thought of it and intend to implement it.

Wikidot is a problem. The api afaik, is broken and renders Wikidot
useless imo. See below for further detail.


Proposal Abstract
==============

Github is really a nice site. I've recently learned that among other
interesting things, it provides for easy uploading and hosting of web
content. Martin and I feel that documentation could all be moved there
for a nice and convenient solution.

Github also provides an api. Automatic generation of documentation and
web content updates are possible.

Doc sets to be covered will be public user docs, as well as
internal/implementation and developer docs for contributers.

Concise, complete, and with plenty of cross-refs / examples / etc.


Doc Generation Tool
================

Not imperative, but for less complexity we should probably use just
one generation tool. Man pages too.

I propose doxygen[1] because feature wise, it (probably) supersedes
anything else.


In Source Documentation
====================

If doxygen is to be used, then comments will change in style and
detail. You will need to consider this when submitting new code. The
doc for contributers will establish a protocol.


Doc Model
========

The Qt application framework is simply so well crafted that I find
myself using it as a model quite a lot. Documentation is certainly no
exception, so take a look at [2]  for a _general_ example of my
vision.


Finally
=====

If I've missed something or you have a concern your comments are
encouraged.. speak up.

Volunteers..  please speak up.

That's enough for now. Watch this thread for more detail and any further RFC


Bibliography
==========

[1] http://www.stack.nl/~dimitri/doxygen/index.html
[2] http://doc.qt.nokia.com/4.7-snapshot/index.html