You are viewing a plain text version of this content. The canonical link for it is here.
Posted to proton@qpid.apache.org by Michael Goulish <mg...@redhat.com> on 2013/02/04 21:56:32 UTC
proposal for docs to aid Proton adoption
I am working on some documentation, examples, & c. to
encourage easy adoption of Proton.
I expect every one of you has had the experience
of trying to use a new software package and not
getting decent help doing so. I would like to
do what I can to help delight any software person who
decides to spend 5 or 10 minutes looking at Proton.
Please take a look at my proposals, below, and let
me know if I missed your pet peeve.
------------------------------ Mick .
Here is a list of the components of the documentation that I
am proposing, with explanations of each.
Documentation Components List
{
1. Quick Start
2. Theory of Operation
3. Component Explanations
4. Riffs
5. Examples
6. Tutorials
7. Error Dictionary
}
Documentation Components Description
{
1. Quick Start
{
A guide to getting up and running, from download to
"hello world" in 10 minutes.
The guide itself should be concise, and should help
to diagnose any common problems you might run into.
This document does not explain anything except what
you need to know to get up and tunning.
}
2. Theory of Operation
{
An overview of the components of the messenger interface,
and an explanation of how those components are used, and
how they interact with each other.
This information will be greatly expanded upon by the
Component Explanations, the Riffs, and the Examples,
but this section gives you the big picture.
To explain with an analogy: my car has a driver's interface
which consists of an ignition switch, a steering wheel, a
clutch, a stick, a gas pedal, and a brake pedal. My
daughter understands the function of each one of those
things separately -- but she still can't drive the car.
To drive the car you also need to know how those subsystems
are all expected to work together. That is a 'theory of
operation'.
}
3. Component Explanations
{
These are like a Theory of Operation, but for individual
components of the Messenger interface. More detailed
than the overall Theory of Operation, but more narrow.
One for each of the following Messenger components:
3.1 accept modes
3.2 errors
3.3 message windows
3.4 messengers
3.5 security
3.6 subscriptions
3.7 timeouts
3.8 trackers
}
4. Riffs // rename these "idioms" ?
{
A 'riff' is a series of function calls that will often be
associated with each other in application code.
Riffs are code-snippets, not complete running examples,
but the code in them would compile and run if it were
inside a complete example.
Each riff also contains an explanation of why the functions
should be used together in this way.
Some types of riffs:
"These functions will often be used together,
in this order."
"These functions are mutually exclusive."
"Use the output from this one as the input to that one."
}
5. Examples
{
Complete running examples, with explanations. These are
narrowly focused on the topic at hand, leaving out code
that may be good practice in a real application, but
may divert attention from the topic at hand.
Eventually, all of these examples should be written in
both C and Java.
Proposed example program topics:
{
messaging patterns
{
point-to-point
fanout
request-reply
publish-subscribe
dead letter
}
security
error handling
timeouts
message windows
sending
receiving
tracker
}
}
6. Tutorials
{
Tutorials are larger than examples, and are focused on
real-world aspects of messaging applications, rather
than being focused on the library code.
A tutorial will typically be longer than an example,
will contain more explanatory text, and will show
and discuss alternative approaches.
Proposed tutorial topics:
{
Security
High Speed Messaging
High Availability
}
}
7. Error Dictionary
{
When you use the library, you may occasionally see errors and
warnings.
What do they mean? What should you do about them?
Are they your problem, or the library's problem?
This document gives the user a detailed explanation of each
error and warning, and suggestions for dealing with them.
}
}
Re: proposal for docs to aid Proton adoption
Posted by Alan Conway <ac...@redhat.com>.
This looks good, looking forward to the doc!
On Mon, 2013-02-04 at 15:56 -0500, Michael Goulish wrote:
> I am working on some documentation, examples, & c. to
> encourage easy adoption of Proton.
>
> I expect every one of you has had the experience
> of trying to use a new software package and not
> getting decent help doing so. I would like to
> do what I can to help delight any software person who
> decides to spend 5 or 10 minutes looking at Proton.
>
> Please take a look at my proposals, below, and let
> me know if I missed your pet peeve.
>
> ------------------------------ Mick .
>
>
>
>
>
> Here is a list of the components of the documentation that I
> am proposing, with explanations of each.
>
>
>
>
> Documentation Components List
> {
> 1. Quick Start
> 2. Theory of Operation
> 3. Component Explanations
> 4. Riffs
> 5. Examples
> 6. Tutorials
> 7. Error Dictionary
> }
>
>
>
> Documentation Components Description
> {
>
> 1. Quick Start
> {
> A guide to getting up and running, from download to
> "hello world" in 10 minutes.
> The guide itself should be concise, and should help
> to diagnose any common problems you might run into.
>
> This document does not explain anything except what
> you need to know to get up and tunning.
> }
>
>
>
> 2. Theory of Operation
> {
> An overview of the components of the messenger interface,
> and an explanation of how those components are used, and
> how they interact with each other.
>
> This information will be greatly expanded upon by the
> Component Explanations, the Riffs, and the Examples,
> but this section gives you the big picture.
>
> To explain with an analogy: my car has a driver's interface
> which consists of an ignition switch, a steering wheel, a
> clutch, a stick, a gas pedal, and a brake pedal. My
> daughter understands the function of each one of those
> things separately -- but she still can't drive the car.
>
> To drive the car you also need to know how those subsystems
> are all expected to work together. That is a 'theory of
> operation'.
> }
>
>
> 3. Component Explanations
> {
> These are like a Theory of Operation, but for individual
> components of the Messenger interface. More detailed
> than the overall Theory of Operation, but more narrow.
>
> One for each of the following Messenger components:
>
> 3.1 accept modes
> 3.2 errors
> 3.3 message windows
> 3.4 messengers
> 3.5 security
> 3.6 subscriptions
> 3.7 timeouts
> 3.8 trackers
> }
>
>
>
> 4. Riffs // rename these "idioms" ?
> {
> A 'riff' is a series of function calls that will often be
> associated with each other in application code.
>
> Riffs are code-snippets, not complete running examples,
> but the code in them would compile and run if it were
> inside a complete example.
>
> Each riff also contains an explanation of why the functions
> should be used together in this way.
>
>
> Some types of riffs:
>
> "These functions will often be used together,
> in this order."
>
> "These functions are mutually exclusive."
>
> "Use the output from this one as the input to that one."
> }
>
>
>
> 5. Examples
> {
> Complete running examples, with explanations. These are
> narrowly focused on the topic at hand, leaving out code
> that may be good practice in a real application, but
> may divert attention from the topic at hand.
>
> Eventually, all of these examples should be written in
> both C and Java.
>
> Proposed example program topics:
> {
> messaging patterns
> {
> point-to-point
> fanout
> request-reply
> publish-subscribe
> dead letter
> }
>
> security
>
> error handling
>
> timeouts
>
> message windows
>
> sending
>
> receiving
>
> tracker
> }
> }
>
>
> 6. Tutorials
> {
> Tutorials are larger than examples, and are focused on
> real-world aspects of messaging applications, rather
> than being focused on the library code.
>
> A tutorial will typically be longer than an example,
> will contain more explanatory text, and will show
> and discuss alternative approaches.
>
> Proposed tutorial topics:
> {
> Security
> High Speed Messaging
> High Availability
> }
> }
>
>
>
> 7. Error Dictionary
> {
> When you use the library, you may occasionally see errors and
> warnings.
>
> What do they mean? What should you do about them?
> Are they your problem, or the library's problem?
>
> This document gives the user a detailed explanation of each
> error and warning, and suggestions for dealing with them.
> }
> }
>
>
>
>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
> For additional commands, e-mail: dev-help@qpid.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org
Re: proposal for docs to aid Proton adoption
Posted by Alan Conway <ac...@redhat.com>.
This looks good, looking forward to the doc!
On Mon, 2013-02-04 at 15:56 -0500, Michael Goulish wrote:
> I am working on some documentation, examples, & c. to
> encourage easy adoption of Proton.
>
> I expect every one of you has had the experience
> of trying to use a new software package and not
> getting decent help doing so. I would like to
> do what I can to help delight any software person who
> decides to spend 5 or 10 minutes looking at Proton.
>
> Please take a look at my proposals, below, and let
> me know if I missed your pet peeve.
>
> ------------------------------ Mick .
>
>
>
>
>
> Here is a list of the components of the documentation that I
> am proposing, with explanations of each.
>
>
>
>
> Documentation Components List
> {
> 1. Quick Start
> 2. Theory of Operation
> 3. Component Explanations
> 4. Riffs
> 5. Examples
> 6. Tutorials
> 7. Error Dictionary
> }
>
>
>
> Documentation Components Description
> {
>
> 1. Quick Start
> {
> A guide to getting up and running, from download to
> "hello world" in 10 minutes.
> The guide itself should be concise, and should help
> to diagnose any common problems you might run into.
>
> This document does not explain anything except what
> you need to know to get up and tunning.
> }
>
>
>
> 2. Theory of Operation
> {
> An overview of the components of the messenger interface,
> and an explanation of how those components are used, and
> how they interact with each other.
>
> This information will be greatly expanded upon by the
> Component Explanations, the Riffs, and the Examples,
> but this section gives you the big picture.
>
> To explain with an analogy: my car has a driver's interface
> which consists of an ignition switch, a steering wheel, a
> clutch, a stick, a gas pedal, and a brake pedal. My
> daughter understands the function of each one of those
> things separately -- but she still can't drive the car.
>
> To drive the car you also need to know how those subsystems
> are all expected to work together. That is a 'theory of
> operation'.
> }
>
>
> 3. Component Explanations
> {
> These are like a Theory of Operation, but for individual
> components of the Messenger interface. More detailed
> than the overall Theory of Operation, but more narrow.
>
> One for each of the following Messenger components:
>
> 3.1 accept modes
> 3.2 errors
> 3.3 message windows
> 3.4 messengers
> 3.5 security
> 3.6 subscriptions
> 3.7 timeouts
> 3.8 trackers
> }
>
>
>
> 4. Riffs // rename these "idioms" ?
> {
> A 'riff' is a series of function calls that will often be
> associated with each other in application code.
>
> Riffs are code-snippets, not complete running examples,
> but the code in them would compile and run if it were
> inside a complete example.
>
> Each riff also contains an explanation of why the functions
> should be used together in this way.
>
>
> Some types of riffs:
>
> "These functions will often be used together,
> in this order."
>
> "These functions are mutually exclusive."
>
> "Use the output from this one as the input to that one."
> }
>
>
>
> 5. Examples
> {
> Complete running examples, with explanations. These are
> narrowly focused on the topic at hand, leaving out code
> that may be good practice in a real application, but
> may divert attention from the topic at hand.
>
> Eventually, all of these examples should be written in
> both C and Java.
>
> Proposed example program topics:
> {
> messaging patterns
> {
> point-to-point
> fanout
> request-reply
> publish-subscribe
> dead letter
> }
>
> security
>
> error handling
>
> timeouts
>
> message windows
>
> sending
>
> receiving
>
> tracker
> }
> }
>
>
> 6. Tutorials
> {
> Tutorials are larger than examples, and are focused on
> real-world aspects of messaging applications, rather
> than being focused on the library code.
>
> A tutorial will typically be longer than an example,
> will contain more explanatory text, and will show
> and discuss alternative approaches.
>
> Proposed tutorial topics:
> {
> Security
> High Speed Messaging
> High Availability
> }
> }
>
>
>
> 7. Error Dictionary
> {
> When you use the library, you may occasionally see errors and
> warnings.
>
> What do they mean? What should you do about them?
> Are they your problem, or the library's problem?
>
> This document gives the user a detailed explanation of each
> error and warning, and suggestions for dealing with them.
> }
> }
>
>
>
>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
> For additional commands, e-mail: dev-help@qpid.apache.org
>
RE: proposal for docs to aid Proton adoption
Posted by Mary Hinton <m....@nc.rr.com>.
Looking forward to your documentation.
Thanks!
Mary
-----Original Message-----
From: Michael Goulish [mailto:mgoulish@redhat.com]
Sent: Monday, February 04, 2013 3:57 PM
To: proton@qpid.apache.org; dev@qpid.apache.org
Subject: proposal for docs to aid Proton adoption
I am working on some documentation, examples, & c. to encourage easy adoption of Proton.
I expect every one of you has had the experience of trying to use a new software package and not getting decent help doing so. I would like to do what I can to help delight any software person who decides to spend 5 or 10 minutes looking at Proton.
Please take a look at my proposals, below, and let me know if I missed your pet peeve.
------------------------------ Mick .
Here is a list of the components of the documentation that I am proposing, with explanations of each.
Documentation Components List
{
1. Quick Start
2. Theory of Operation
3. Component Explanations
4. Riffs
5. Examples
6. Tutorials
7. Error Dictionary
}
Documentation Components Description
{
1. Quick Start
{
A guide to getting up and running, from download to
"hello world" in 10 minutes.
The guide itself should be concise, and should help
to diagnose any common problems you might run into.
This document does not explain anything except what
you need to know to get up and tunning.
}
2. Theory of Operation
{
An overview of the components of the messenger interface,
and an explanation of how those components are used, and
how they interact with each other.
This information will be greatly expanded upon by the
Component Explanations, the Riffs, and the Examples,
but this section gives you the big picture.
To explain with an analogy: my car has a driver's interface
which consists of an ignition switch, a steering wheel, a
clutch, a stick, a gas pedal, and a brake pedal. My
daughter understands the function of each one of those
things separately -- but she still can't drive the car.
To drive the car you also need to know how those subsystems
are all expected to work together. That is a 'theory of
operation'.
}
3. Component Explanations
{
These are like a Theory of Operation, but for individual
components of the Messenger interface. More detailed
than the overall Theory of Operation, but more narrow.
One for each of the following Messenger components:
3.1 accept modes
3.2 errors
3.3 message windows
3.4 messengers
3.5 security
3.6 subscriptions
3.7 timeouts
3.8 trackers
}
4. Riffs // rename these "idioms" ?
{
A 'riff' is a series of function calls that will often be
associated with each other in application code.
Riffs are code-snippets, not complete running examples,
but the code in them would compile and run if it were
inside a complete example.
Each riff also contains an explanation of why the functions
should be used together in this way.
Some types of riffs:
"These functions will often be used together,
in this order."
"These functions are mutually exclusive."
"Use the output from this one as the input to that one."
}
5. Examples
{
Complete running examples, with explanations. These are
narrowly focused on the topic at hand, leaving out code
that may be good practice in a real application, but
may divert attention from the topic at hand.
Eventually, all of these examples should be written in
both C and Java.
Proposed example program topics:
{
messaging patterns
{
point-to-point
fanout
request-reply
publish-subscribe
dead letter
}
security
error handling
timeouts
message windows
sending
receiving
tracker
}
}
6. Tutorials
{
Tutorials are larger than examples, and are focused on
real-world aspects of messaging applications, rather
than being focused on the library code.
A tutorial will typically be longer than an example,
will contain more explanatory text, and will show
and discuss alternative approaches.
Proposed tutorial topics:
{
Security
High Speed Messaging
High Availability
}
}
7. Error Dictionary
{
When you use the library, you may occasionally see errors and
warnings.
What do they mean? What should you do about them?
Are they your problem, or the library's problem?
This document gives the user a detailed explanation of each
error and warning, and suggestions for dealing with them.
}
}
Re: proposal for docs to aid Proton adoption
Posted by Phil Harvey <ph...@philharveyonline.com>.
Hi Michael,
Thank you for doing this. There's obviously a lot of interest in Proton
but since it's quite an original library some new users do find it
confusing.
When do you expect to finish the first draft? The reason I ask is that I
know some Proton talks are happening at ApacheCon in a couple of weeks, so
I was wondering what we expect to have ready by then.
What format are you planning to produce the documentation in (eg dobook, or
HTML, or something else)? Presumably the documentation will be uploaded to
http://qpid.apache.org/proton?
I got the sense from your document outline that the main audience would be
users of the Messenger API. What, if anything, do you plan to write for
developers who are primarily using the Engine and Transport APIs?
Thanks again,
Phil
On 4 February 2013 20:56, Michael Goulish <mg...@redhat.com> wrote:
>
> I am working on some documentation, examples, & c. to
> encourage easy adoption of Proton.
>
> I expect every one of you has had the experience
> of trying to use a new software package and not
> getting decent help doing so. I would like to
> do what I can to help delight any software person who
> decides to spend 5 or 10 minutes looking at Proton.
>
> Please take a look at my proposals, below, and let
> me know if I missed your pet peeve.
>
> ------------------------------ Mick .
>
>
>
>
>
> Here is a list of the components of the documentation that I
> am proposing, with explanations of each.
>
>
>
>
> Documentation Components List
> {
> 1. Quick Start
> 2. Theory of Operation
> 3. Component Explanations
> 4. Riffs
> 5. Examples
> 6. Tutorials
> 7. Error Dictionary
> }
>
>
>
> Documentation Components Description
> {
>
> 1. Quick Start
> {
> A guide to getting up and running, from download to
> "hello world" in 10 minutes.
> The guide itself should be concise, and should help
> to diagnose any common problems you might run into.
>
> This document does not explain anything except what
> you need to know to get up and tunning.
> }
>
>
>
> 2. Theory of Operation
> {
> An overview of the components of the messenger interface,
> and an explanation of how those components are used, and
> how they interact with each other.
>
> This information will be greatly expanded upon by the
> Component Explanations, the Riffs, and the Examples,
> but this section gives you the big picture.
>
> To explain with an analogy: my car has a driver's interface
> which consists of an ignition switch, a steering wheel, a
> clutch, a stick, a gas pedal, and a brake pedal. My
> daughter understands the function of each one of those
> things separately -- but she still can't drive the car.
>
> To drive the car you also need to know how those subsystems
> are all expected to work together. That is a 'theory of
> operation'.
> }
>
>
> 3. Component Explanations
> {
> These are like a Theory of Operation, but for individual
> components of the Messenger interface. More detailed
> than the overall Theory of Operation, but more narrow.
>
> One for each of the following Messenger components:
>
> 3.1 accept modes
> 3.2 errors
> 3.3 message windows
> 3.4 messengers
> 3.5 security
> 3.6 subscriptions
> 3.7 timeouts
> 3.8 trackers
> }
>
>
>
> 4. Riffs // rename these "idioms" ?
> {
> A 'riff' is a series of function calls that will often be
> associated with each other in application code.
>
> Riffs are code-snippets, not complete running examples,
> but the code in them would compile and run if it were
> inside a complete example.
>
> Each riff also contains an explanation of why the functions
> should be used together in this way.
>
>
> Some types of riffs:
>
> "These functions will often be used together,
> in this order."
>
> "These functions are mutually exclusive."
>
> "Use the output from this one as the input to that one."
> }
>
>
>
> 5. Examples
> {
> Complete running examples, with explanations. These are
> narrowly focused on the topic at hand, leaving out code
> that may be good practice in a real application, but
> may divert attention from the topic at hand.
>
> Eventually, all of these examples should be written in
> both C and Java.
>
> Proposed example program topics:
> {
> messaging patterns
> {
> point-to-point
> fanout
> request-reply
> publish-subscribe
> dead letter
> }
>
> security
>
> error handling
>
> timeouts
>
> message windows
>
> sending
>
> receiving
>
> tracker
> }
> }
>
>
> 6. Tutorials
> {
> Tutorials are larger than examples, and are focused on
> real-world aspects of messaging applications, rather
> than being focused on the library code.
>
> A tutorial will typically be longer than an example,
> will contain more explanatory text, and will show
> and discuss alternative approaches.
>
> Proposed tutorial topics:
> {
> Security
> High Speed Messaging
> High Availability
> }
> }
>
>
>
> 7. Error Dictionary
> {
> When you use the library, you may occasionally see errors and
> warnings.
>
> What do they mean? What should you do about them?
> Are they your problem, or the library's problem?
>
> This document gives the user a detailed explanation of each
> error and warning, and suggestions for dealing with them.
> }
> }
>
>
>
>
>
>
>
>
Re: proposal for docs to aid Proton adoption
Posted by Chuck Rolke <cr...@redhat.com>.
Hi Mick,
Indeed the Riffs chapter needs a rename. Actually at this stage of
maturity a Riffs/Patterns chapter may not be possible yet: patterns
don't exist!
Have you thought about diagrams? There's a ton of image editors
out there (Visio, OpenOffice Draw, DIA, ...) and I'd agree to
use *any* of them support your effort.
Three points on diagrams:
1. The Qpid document that sort of does what you are describing,
Programming-in-Apache-Qpid, goes through the whole exercise with no
pictures. This makes it hard to read and the images that come into
the readers' heads may not be the ones that the authors intend.
2. The AMQP 1.0 spec uses plenty of pictures in ascii art. I used
PECO on my VAX and VT100 to edit ascii art back in the '80s.
I love ascii art but new documentation can do better.
3. An example of where profoundly simple diagrams effectively
tell a story is
http://www.rabbitmq.com/resources/RabbitMQ_MessagingInTheCloud_VMworld_2010_MS.pdf
This document has the level of pictures that I'm talking about.
Please consider making a family of diagrams a requirement for
your document.
-Chuck
----- Original Message -----
> From: "Steve Huston" <sh...@riverace.com>
> To: dev@qpid.apache.org
> Sent: Monday, February 4, 2013 5:54:38 PM
> Subject: RE: proposal for docs to aid Proton adoption
>
> This is a great start, Mick - nice job.
>
> I would prefer Riffs to be named Idioms, or maybe better, Patterns.
>
> > -----Original Message-----
> > From: Michael Goulish [mailto:mgoulish@redhat.com]
> > Sent: Monday, February 04, 2013 3:57 PM
> > To: proton@qpid.apache.org; dev@qpid.apache.org
> > Subject: proposal for docs to aid Proton adoption
> >
> >
> > I am working on some documentation, examples, & c. to encourage
> > easy
> > adoption of Proton.
> >
> > I expect every one of you has had the experience of trying to use a
> > new
> > software package and not getting decent help doing so. I would
> > like to do
> > what I can to help delight any software person who decides to spend
> > 5 or 10
> > minutes looking at Proton.
> >
> > Please take a look at my proposals, below, and let me know if I
> > missed your
> > pet peeve.
> >
> > ------------------------------ Mick .
> >
> >
> >
> >
> >
> > Here is a list of the components of the documentation that I am
> > proposing,
> > with explanations of each.
> >
> >
> >
> >
> > Documentation Components List
> > {
> > 1. Quick Start
> > 2. Theory of Operation
> > 3. Component Explanations
> > 4. Riffs
> > 5. Examples
> > 6. Tutorials
> > 7. Error Dictionary
> > }
> >
> >
> >
> > Documentation Components Description
> > {
> >
> > 1. Quick Start
> > {
> > A guide to getting up and running, from download to
> > "hello world" in 10 minutes.
> > The guide itself should be concise, and should help
> > to diagnose any common problems you might run into.
> >
> > This document does not explain anything except what
> > you need to know to get up and tunning.
> > }
> >
> >
> >
> > 2. Theory of Operation
> > {
> > An overview of the components of the messenger interface,
> > and an explanation of how those components are used, and
> > how they interact with each other.
> >
> > This information will be greatly expanded upon by the
> > Component Explanations, the Riffs, and the Examples,
> > but this section gives you the big picture.
> >
> > To explain with an analogy: my car has a driver's interface
> > which consists of an ignition switch, a steering wheel, a
> > clutch, a stick, a gas pedal, and a brake pedal. My
> > daughter understands the function of each one of those
> > things separately -- but she still can't drive the car.
> >
> > To drive the car you also need to know how those subsystems
> > are all expected to work together. That is a 'theory of
> > operation'.
> > }
> >
> >
> > 3. Component Explanations
> > {
> > These are like a Theory of Operation, but for individual
> > components of the Messenger interface. More detailed
> > than the overall Theory of Operation, but more narrow.
> >
> > One for each of the following Messenger components:
> >
> > 3.1 accept modes
> > 3.2 errors
> > 3.3 message windows
> > 3.4 messengers
> > 3.5 security
> > 3.6 subscriptions
> > 3.7 timeouts
> > 3.8 trackers
> > }
> >
> >
> >
> > 4. Riffs // rename these "idioms" ?
> > {
> > A 'riff' is a series of function calls that will often be
> > associated with each other in application code.
> >
> > Riffs are code-snippets, not complete running examples,
> > but the code in them would compile and run if it were
> > inside a complete example.
> >
> > Each riff also contains an explanation of why the functions
> > should be used together in this way.
> >
> >
> > Some types of riffs:
> >
> > "These functions will often be used together,
> > in this order."
> >
> > "These functions are mutually exclusive."
> >
> > "Use the output from this one as the input to that one."
> > }
> >
> >
> >
> > 5. Examples
> > {
> > Complete running examples, with explanations. These are
> > narrowly focused on the topic at hand, leaving out code
> > that may be good practice in a real application, but
> > may divert attention from the topic at hand.
> >
> > Eventually, all of these examples should be written in
> > both C and Java.
> >
> > Proposed example program topics:
> > {
> > messaging patterns
> > {
> > point-to-point
> > fanout
> > request-reply
> > publish-subscribe
> > dead letter
> > }
> >
> > security
> >
> > error handling
> >
> > timeouts
> >
> > message windows
> >
> > sending
> >
> > receiving
> >
> > tracker
> > }
> > }
> >
> >
> > 6. Tutorials
> > {
> > Tutorials are larger than examples, and are focused on
> > real-world aspects of messaging applications, rather
> > than being focused on the library code.
> >
> > A tutorial will typically be longer than an example,
> > will contain more explanatory text, and will show
> > and discuss alternative approaches.
> >
> > Proposed tutorial topics:
> > {
> > Security
> > High Speed Messaging
> > High Availability
> > }
> > }
> >
> >
> >
> > 7. Error Dictionary
> > {
> > When you use the library, you may occasionally see errors and
> > warnings.
> >
> > What do they mean? What should you do about them?
> > Are they your problem, or the library's problem?
> >
> > This document gives the user a detailed explanation of each
> > error and warning, and suggestions for dealing with them.
> > }
> > }
> >
> >
> >
> >
> >
> >
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org For
> > additional
> > commands, e-mail: dev-help@qpid.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
> For additional commands, e-mail: dev-help@qpid.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org
RE: proposal for docs to aid Proton adoption
Posted by Steve Huston <sh...@riverace.com>.
This is a great start, Mick - nice job.
I would prefer Riffs to be named Idioms, or maybe better, Patterns.
> -----Original Message-----
> From: Michael Goulish [mailto:mgoulish@redhat.com]
> Sent: Monday, February 04, 2013 3:57 PM
> To: proton@qpid.apache.org; dev@qpid.apache.org
> Subject: proposal for docs to aid Proton adoption
>
>
> I am working on some documentation, examples, & c. to encourage easy
> adoption of Proton.
>
> I expect every one of you has had the experience of trying to use a new
> software package and not getting decent help doing so. I would like to do
> what I can to help delight any software person who decides to spend 5 or 10
> minutes looking at Proton.
>
> Please take a look at my proposals, below, and let me know if I missed your
> pet peeve.
>
> ------------------------------ Mick .
>
>
>
>
>
> Here is a list of the components of the documentation that I am proposing,
> with explanations of each.
>
>
>
>
> Documentation Components List
> {
> 1. Quick Start
> 2. Theory of Operation
> 3. Component Explanations
> 4. Riffs
> 5. Examples
> 6. Tutorials
> 7. Error Dictionary
> }
>
>
>
> Documentation Components Description
> {
>
> 1. Quick Start
> {
> A guide to getting up and running, from download to
> "hello world" in 10 minutes.
> The guide itself should be concise, and should help
> to diagnose any common problems you might run into.
>
> This document does not explain anything except what
> you need to know to get up and tunning.
> }
>
>
>
> 2. Theory of Operation
> {
> An overview of the components of the messenger interface,
> and an explanation of how those components are used, and
> how they interact with each other.
>
> This information will be greatly expanded upon by the
> Component Explanations, the Riffs, and the Examples,
> but this section gives you the big picture.
>
> To explain with an analogy: my car has a driver's interface
> which consists of an ignition switch, a steering wheel, a
> clutch, a stick, a gas pedal, and a brake pedal. My
> daughter understands the function of each one of those
> things separately -- but she still can't drive the car.
>
> To drive the car you also need to know how those subsystems
> are all expected to work together. That is a 'theory of
> operation'.
> }
>
>
> 3. Component Explanations
> {
> These are like a Theory of Operation, but for individual
> components of the Messenger interface. More detailed
> than the overall Theory of Operation, but more narrow.
>
> One for each of the following Messenger components:
>
> 3.1 accept modes
> 3.2 errors
> 3.3 message windows
> 3.4 messengers
> 3.5 security
> 3.6 subscriptions
> 3.7 timeouts
> 3.8 trackers
> }
>
>
>
> 4. Riffs // rename these "idioms" ?
> {
> A 'riff' is a series of function calls that will often be
> associated with each other in application code.
>
> Riffs are code-snippets, not complete running examples,
> but the code in them would compile and run if it were
> inside a complete example.
>
> Each riff also contains an explanation of why the functions
> should be used together in this way.
>
>
> Some types of riffs:
>
> "These functions will often be used together,
> in this order."
>
> "These functions are mutually exclusive."
>
> "Use the output from this one as the input to that one."
> }
>
>
>
> 5. Examples
> {
> Complete running examples, with explanations. These are
> narrowly focused on the topic at hand, leaving out code
> that may be good practice in a real application, but
> may divert attention from the topic at hand.
>
> Eventually, all of these examples should be written in
> both C and Java.
>
> Proposed example program topics:
> {
> messaging patterns
> {
> point-to-point
> fanout
> request-reply
> publish-subscribe
> dead letter
> }
>
> security
>
> error handling
>
> timeouts
>
> message windows
>
> sending
>
> receiving
>
> tracker
> }
> }
>
>
> 6. Tutorials
> {
> Tutorials are larger than examples, and are focused on
> real-world aspects of messaging applications, rather
> than being focused on the library code.
>
> A tutorial will typically be longer than an example,
> will contain more explanatory text, and will show
> and discuss alternative approaches.
>
> Proposed tutorial topics:
> {
> Security
> High Speed Messaging
> High Availability
> }
> }
>
>
>
> 7. Error Dictionary
> {
> When you use the library, you may occasionally see errors and
> warnings.
>
> What do they mean? What should you do about them?
> Are they your problem, or the library's problem?
>
> This document gives the user a detailed explanation of each
> error and warning, and suggestions for dealing with them.
> }
> }
>
>
>
>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org For additional
> commands, e-mail: dev-help@qpid.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org
RE: proposal for docs to aid Proton adoption
Posted by Mary Hinton <m....@nc.rr.com>.
Looking forward to your documentation.
Thanks!
Mary
-----Original Message-----
From: Michael Goulish [mailto:mgoulish@redhat.com]
Sent: Monday, February 04, 2013 3:57 PM
To: proton@qpid.apache.org; dev@qpid.apache.org
Subject: proposal for docs to aid Proton adoption
I am working on some documentation, examples, & c. to encourage easy adoption of Proton.
I expect every one of you has had the experience of trying to use a new software package and not getting decent help doing so. I would like to do what I can to help delight any software person who decides to spend 5 or 10 minutes looking at Proton.
Please take a look at my proposals, below, and let me know if I missed your pet peeve.
------------------------------ Mick .
Here is a list of the components of the documentation that I am proposing, with explanations of each.
Documentation Components List
{
1. Quick Start
2. Theory of Operation
3. Component Explanations
4. Riffs
5. Examples
6. Tutorials
7. Error Dictionary
}
Documentation Components Description
{
1. Quick Start
{
A guide to getting up and running, from download to
"hello world" in 10 minutes.
The guide itself should be concise, and should help
to diagnose any common problems you might run into.
This document does not explain anything except what
you need to know to get up and tunning.
}
2. Theory of Operation
{
An overview of the components of the messenger interface,
and an explanation of how those components are used, and
how they interact with each other.
This information will be greatly expanded upon by the
Component Explanations, the Riffs, and the Examples,
but this section gives you the big picture.
To explain with an analogy: my car has a driver's interface
which consists of an ignition switch, a steering wheel, a
clutch, a stick, a gas pedal, and a brake pedal. My
daughter understands the function of each one of those
things separately -- but she still can't drive the car.
To drive the car you also need to know how those subsystems
are all expected to work together. That is a 'theory of
operation'.
}
3. Component Explanations
{
These are like a Theory of Operation, but for individual
components of the Messenger interface. More detailed
than the overall Theory of Operation, but more narrow.
One for each of the following Messenger components:
3.1 accept modes
3.2 errors
3.3 message windows
3.4 messengers
3.5 security
3.6 subscriptions
3.7 timeouts
3.8 trackers
}
4. Riffs // rename these "idioms" ?
{
A 'riff' is a series of function calls that will often be
associated with each other in application code.
Riffs are code-snippets, not complete running examples,
but the code in them would compile and run if it were
inside a complete example.
Each riff also contains an explanation of why the functions
should be used together in this way.
Some types of riffs:
"These functions will often be used together,
in this order."
"These functions are mutually exclusive."
"Use the output from this one as the input to that one."
}
5. Examples
{
Complete running examples, with explanations. These are
narrowly focused on the topic at hand, leaving out code
that may be good practice in a real application, but
may divert attention from the topic at hand.
Eventually, all of these examples should be written in
both C and Java.
Proposed example program topics:
{
messaging patterns
{
point-to-point
fanout
request-reply
publish-subscribe
dead letter
}
security
error handling
timeouts
message windows
sending
receiving
tracker
}
}
6. Tutorials
{
Tutorials are larger than examples, and are focused on
real-world aspects of messaging applications, rather
than being focused on the library code.
A tutorial will typically be longer than an example,
will contain more explanatory text, and will show
and discuss alternative approaches.
Proposed tutorial topics:
{
Security
High Speed Messaging
High Availability
}
}
7. Error Dictionary
{
When you use the library, you may occasionally see errors and
warnings.
What do they mean? What should you do about them?
Are they your problem, or the library's problem?
This document gives the user a detailed explanation of each
error and warning, and suggestions for dealing with them.
}
}
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org