Hi Matt, >> No, so I suggest when the startersguide is finished, we delete the old >> samples and rename the new ones to the old name ;) > > This will break tutorials within the tutorial book, Well, then you have your answer: there is a use for both samples.
> so maybe you can > put all of your samples into a seperate folder. There is only one folder for all samples and it contains a lot of different ones. A lot of them make sense on their own (like the blink examples), some mostly in relation to a document (like the i2c samples of Seb). All files can be recognised by their filename. What purpose does it serve to put these samples into an other directory? Or do you mean it should not be part of jallib distribution? > The only solution > would be to agree to put it all into one book somehow. I don't see why this would be the only solution. I don't even see what the problem is you want to solve. This is the basic issue in this discussion: you argue there must be only one book. More books is bad, one book is good. But you don't give arguments for this. So what problem is there to solve? I described the three 'books' we need IMO and why. The tutorial book is one of them, I am working on the next one. > Have you looked > over the tutorial book? Can you please give some feedback? Of course I have looked at the tutorial book. It is a collection of independent articles that give detailed information about theory, hardware and software on a specific topic. So if you want to get started on a specific subject, you can pick the relevant article and get started. Very usefull. > Creating this book does create a "different branch" doesn't it? No, it is not a different branche, it is a different book. > Please put some more thought into putting it all into one book. Tell me why! > As you > can see, the website, dita, etc, is working good. It already has users/ > readers and is already being advertised. It also has at least 2 > contributors (seb and myself), Sunish has also had some interest. Many > others have given suggestions. Beeing a different book does not mean it is on an other world. It is part of jallib, will be part of the distribution and will be hosted on the website. > As you said, it is hard for just one > person to write a book. Please try to find a good solution that we can > all agree on. I have given my suggestions. So have I, about a year ago and again last summer but I am hapy to reapeat myself once again ;) I think we need three books: the tutorial book with independent chapters, an introdcution book and a reference guide. We started writing independent tutorials on the blog over a year ago and they are now collected and extended into the tutorial book. And since each chapter is independent, the work can easily divided between persons and still give good result. The goal of the introduction book is to cover (touch) all relevant subjects. The idea is that someone reads it cover-to-cover so there should be not too much duplication and concepts must be introduced in a logical way. I use samples as a guidline in this document and described a basic hardware configuration as a reference platform. I won't go into much detail on hardware, programming etc., but refer to tutorials for this. I think the introduction book is usefull, even when people (with some experience in microcontrollers) don't actually try the samples. Key issue here is that the line of the book is important. This means you need at least a chief editor to achieve the goal. Third book required is a reference manual. Kyle invests more in his documentation, which makes it better and more complete. But it is very brief, a more formal specification. IMO the reference manual is as complete and precise as Kyle's documentation, but with more explanation, detail, tricks and examples. Take a look at the old pjal manual to see what I mean. We can't expect Kyle to do this (by) himself: maintaining the compiler is a tremendous job and has priority over a reference guide. A reference guide needs someone (or a small group) to create and maintain it in a consistent way. And we realy need such a document too. While writing the introduction guide, I did quite a few tests to determine the exact behavior of the language. And I even had to dig in old postings to find details about features that are not documtented... > > Do you not agree that the tutorial book takes users by the hand in the > "getting started" section? I agree and this is valueble. It gets people started. But it does not give them an overview. Joep -- You received this message because you are subscribed to the Google Groups "jallib" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/jallib?hl=en.
