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:[email protected]] > Sent: Monday, February 04, 2013 3:57 PM > To: [email protected]; [email protected] > 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: [email protected] For additional > commands, e-mail: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
