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: [email protected]
> For additional commands, e-mail: [email protected]
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
