On Fri, Jul 9, 2010 at 7:30 AM, Peter Alexander <vel.ac...@gmail.com> wrote: > 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.
Let me just add here that by disarray I'm referring to 0mq1 documentation being commingled with 0mq2. Obviously the Man pages, Cookbook and new blog entries are quite nice. (hope I didn't inadvertently rub anyone wrong :-/ ) > > 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 zeromq-dev@lists.zeromq.org http://lists.zeromq.org/mailman/listinfo/zeromq-dev
