I do agree with you that having documentation committed alongside code is the right approach.
I propose that we write this documentation in Markdown syntax. That gives us (or our users) the option of easily generating HTML whilst keeping the barrier to entry low for authors. I recognise that Markdown lacks the semantic richness of Docbook (used for the Qpid Broker), but I believe that's ok in this case since our documentation should be quite short (or we're doing something wrong). Phil On Feb 25, 2013 7:07 PM, "Rajith Attapattu" <rajit...@gmail.com> wrote: > I'm strong believer in maintaining our docs in the source tree, as it > makes it easy to release docs along side the code. > Also it helps keep the docs current. > The wiki based documentation in the past had many issues, the chief > complaint being stale most of the time. > > We could look at doing something similar to the qpid docs, or we could > also use this opportunity to experiment with a different approach/tool > set. > > Rajith > > On Mon, Feb 25, 2013 at 1:50 PM, Michael Goulish <mgoul...@redhat.com> > wrote: > > > > I think I will be landing it in the code tree first, and > > from there, I don't know. Any suggestions? > > > > In the code -- I assume it should be at the top level? > > i.e. a sibling of the README file? i.e. > > > > > > qpid-proton-0.4/pulitzer_prize_winning_documentation > > > > > > or something along those lines? > > > > Agree? Disagree? > > > > > > > > > > > > > > ----- Original Message ----- > > From: "Phil Harvey" <p...@philharveyonline.com> > > To: proton@qpid.apache.org > > Sent: Monday, February 25, 2013 12:14:00 PM > > Subject: Re: [documentation] -- Intro to Proton > > > > Hi Michael, > > > > Maybe you didn't see my previous question (or maybe I didn't see your > > answer). > > > > Where are you intending to store this documentation? Similarly, where > are > > you intending to publish it, e.g. as HTML and/or PDF on our web site, as > a > > wiki page etc? > > > > Thanks > > Phil > > > > > > On 25 February 2013 16:15, Michael Goulish <mgoul...@redhat.com> wrote: > > > >> > >> Here's the introduction I'm planning on. > >> > >> If anyone has any opinions, I'd be happy to get them -- > >> is there too much detail for a quick intro? Too > >> little? A crucial bit I left out? Something I got wrong? > >> > >> ############################################################## > >> > >> > >> > >> > >> > >> Introduction to Proton > >> =============================================== > >> > >> > >> > >> The Messenger interface is a simple, high-level API that lets > >> you create point-to-point messaging applications quickly and easily. > >> > >> The interface offers four main categories of functionality. > >> > >> > >> > >> > >> Messenger Operation > >> ----------------------------------------------- > >> > >> There are only a few operations that are not directly concerning > >> with message transmission. > >> > >> A messenger can be created, named, and freed. It can be started > >> and stopped, and it can be checked for errors after any operation. > >> > >> > >> > >> > >> > >> Sending and Receiving > >> ----------------------------------------------- > >> > >> Both sending and receiving happen in two stages, the inner stage > >> moving the message between your application and a queue, the > >> outer stage transmitting messages between your queues and > >> remote messaging nodes. > >> > >> By changing the ratio of transmissions to queue transfers, you > >> can optimize your messaging application for message latency or > >> for overall throughput. > >> > >> Subscriptions control what sources your messenger can receive > >> from, and what sources it can send to. Your messenger > >> subscribes to the sources you want to receive from, while your > >> outgoing messages will be received by messengers that have > >> subscribed to your outgoing address. > >> > >> > >> > >> > >> > >> Message Disposition > >> ----------------------------------------------- > >> > >> When you receive messages, you must either accept or reject them. > >> > >> You can either configure your messenger to automatically accept > >> all messages that you get, or you can exercise finer control over > >> message acceptance and rejection, individually or in groups. > >> > >> Trackers and Windows let you set or check the disposition of > >> messages in groups. Applying the disposition operations to > >> groups of messages can improve your system's throughput. > >> > >> When receiving messages, you can create a tracker > >> for the most recently received message, and later use that tracker > >> to accept or reject all messages up to (and including) that one. > >> > >> When sending messages, you can create a tracker for your most > >> recently sent message, and later use it to inquire about the > >> remote disposition of all sent messages up to that point. > >> If you don't want to let a receiver make you wait forever > >> to see what he's going to do, you can set a timeout that will > >> control how long he can take making up his mind. > >> > >> By using incoming and outgoing Windows, you can limit the > >> number of messages that these operations affect. > >> > >> > >> > >> > >> > >> > >> > >> Security > >> ----------------------------------------------- > >> > >> The messenger interface allows you to use the Secure Sockets Layer > >> by exposing an interface to the OpenSSL library. > >> > >> > >> > >> >
