Looking forward to your documentation.
Thanks!
Mary

-----Original Message-----
From: Michael Goulish [mailto:mgoul...@redhat.com] 
Sent: Monday, February 04, 2013 3:57 PM
To: proton@qpid.apache.org; d...@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.
  }
}









Reply via email to