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.
>>
>>
>>
>>

Reply via email to