Answer for Item 1
toggle quoted messageShow quoted text
Here are my ideas for Item 1: The target reader:
Who is the target reader for the Pony Book?
The target reader should be the typical developer who has basic working knowledge of object-oriented programming. Knowledge of concurrency and parallel computing should not be presupposed.
I think that an open source Pony Book could cater for all kinds of readers: it should contain all kinds of explanations directed at levels varying from novice to expert, as well as articles for developers working with differing primary programming languages. Each document should indicate the presupposed level.
If it ever comes to a printed book, we could simply take out the documents at the average developer level and blend these to a book text. This could then contain links to explanations at a more novice or expert level.
But starting off we need to provide material for the typical developer, because only in this way can the Pony community grow the quickest.
General comments for a Pony Book / website
- The Tutorial on the Pony website starts out really good and approachable; the first half is quite digestible for a novice programmer.
But when the Capabilities chapter starts the abstraction level rises up 2 orders of magnitude; that whole chapter is quite unapproachable for the average developer. Much more intelligible examples are needed.
- There should be some code samples on the front page
- All code examples in a book should be runnable, or at least the code provided with the book should be runnable
- Knowledge of how to work with gdb or lldb should not be taken for granted: à a debugging tutorial working with Pony is needed
From: Sean T. Allen [mailto:sean@...]
Thanks for expressing interesting in being part of “The Pony Book”. I like that I am already seeing it mentioned in the community with the appropriate scare quotes around it like “The Book”. This pleases me greatly.
I’ve been delaying writing this first email until the State of the Stable survey was done running and I had written up the results. I strongly suggest that you go check them out, they are the best means we currently have for getting insight into the people who are checking out/using Pony. You can find my writeup at https://groups.io/g/pony/wiki/State-of-the-Stable-2016 and from there, you can get the raw data if you are interested. There’s some interesting stuff in the Wufoo report that didn’t make the write up.
I have two tasks for anyone who wants to participate in the book. They are detailed below:
Write up a description of who is the target reader. This should be at least a couple paragraphs and no more than 1 page. This is one of the most important things we are going to do. We need, as a group, to come to an agreement on who the reader will be. The final document we come up with after getting everyone’s input will define what the basic knowledge a read is expected to have. Let me give you an example:
Debugging Pony is done using GDB or LLDB, is that something we expect every reader to know? If not, we need to teach the reader how to use GDB or LLDB before we teach them how to debug Do they have to have experience with concurrent code via threading? It’s certainly a large part of the story for how Pony is “marketed” but, is there really anything where that should be required? Can we write a book that can teach both the threaded Java/C programmer as well as the Python on Ruby programmer? Do we want to try?
The point of this exercise is to establish a baseline. Any knowledge that isn’t in the baseline that is required to understand something in the book has to be included in the book.
Start the “Pony for X” series. What is the “Pony for X” series? Its an intro to Pony written for people with experience in different languages. We’ll figure out together how we can divide up as many languages as possible and we’ll each write something like “Pony for C programmers”, “Pony for Rubyists” etc. The goal of each is to explain to someone who is moderately competent in the language why they should care about Pony. What does Pony provide, what does it look like, what are its important features.
Note, that I said “moderately competent”, that’s a really handwavey term. I could have said “someone with a year or two experience with the language” but that is also a handwave. You’ll need to come up a target audience and what they know for the “Pony for X” that you write as well. And it should look different than what you came up with for Item 1 because, its a much more constrained audience pool.
I expect that a rough draft of one of these would be 8 to 12 pages but that too is also a hand wave. Write what you can and we can work on editing them together as a group.
So, let everyone know what language you would like to step up and handle.
toggle quoted messageShow quoted text
Target reader: I've sort of answered this in negative, by saying where I think the focus should be, rather than what the baseline is.
My preference is for something which is targeted more at the experienced developer. I don't see much immediate advantage for Pony in targeting, or even helping, the truly novice developer. That doesn't seem to be Pony's initial goal (might be wrong!). This perhaps also comes with wanting to write the kind of language book I like best: blasts through the more standard features in a clear and comprehensive way, but then focusses in depth on the hairier bits. For Pony those are, for me:
This should be well-covered (gdb et al), to support developers who aren't coming from C/C++. Do we cover the C API?
Types and capabilities
Capabilities, as Ivo says, are where the action is for Pony. They, and the type system in general, will need a lot of attention and examples to avoid leaving people hanging. There's plenty in there besides capabilities: generics, union types, intersection types, traits and interfaces.
On Tue, Mar 15, 2016 at 3:15 PM, Ivo Balbaert <ivo.balbaert@...> wrote: