qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alan Conway <acon...@redhat.com>
Subject Re: proposal for docs to aid Proton adoption
Date Wed, 06 Feb 2013 16:12:35 GMT
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


Mime
View raw message