Phil, I think it's worth experimenting with an approach that has a low barrier-to-entry. Markdown seems very very appealing. Anytime you can get away with plain text, it's great.
And as Alan mentioned, the source doc itself can be a finished product. So my +1 for trying this. Regards, Rajith On Mon, Feb 25, 2013 at 8:56 PM, Phil Harvey <p...@philharveyonline.com> wrote: > 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. >> >> >> >> >> >> >> >> >>
