[zeromq-dev] Documentation Proposal
vel.accel at gmail.com
Fri Jul 9 13:30:04 CEST 2010
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.
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.
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 because feature wise, it (probably) supersedes
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.
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  for a _general_ example of my
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
More information about the zeromq-dev