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 _______________________________________________ zeromq-dev mailing list [email protected] http://lists.zeromq.org/mailman/listinfo/zeromq-dev
