Hi guys, Here are some comments I can have reading this doc:
- license: maybe a Creative Common license would better fit. CC is for content, while GPL is for code. Reading GPL, most articles won't apply to this documentation. More, Google Code two ways for licensing a project: 1 for the code (GPL, BSD, ...), 1 for the content (CC). There are different options in CC, wherever you want to allow commercial or not for instance. See: http://creativecommons.org/choose/ - I agree with Sunish about migration beeing independent from jalv2/jallib introduction. I would even say this doesn't sound like a conversion/migration guide, it is, as the title says, an introduction. The part about Bertlibs (in Introduction) could also be named "Why jallib ?". - generally speaking, and taking ADC as an example, I don't think it's enough to get started with this information. As far as I'm concerned, I do need some detailed instructions. What is ADC ? It may be out of scope, still few words explaining what it does, an application example would help the novice to understand what this is about. Your mail about having to set ADC_NCHANNEL vs. not set_analog_pin() available and the part in my blog post could definitively be put here. Few words about theory, a global overview about it's handled in jalilb, then practice. I think when introducing a subject like a peripheral, there should be detailed instructions, hardware setup, photos, just to show how it looks like. Take user by the hand. This is what "Step by step" posts are about. We should discuss about integrate them directly into the document. This is my next bullet. - We probably need a way to centralize all the documentation, to avoid duplication and maintenance nightmare that comes with it. I don't know what is the original format for this document, but we'd need a text base format, not Word for instance. If we need to compile different sources of information, we need a way to do this easily. And it should be under SVN. With a text mode doc, you can also diff versions (and it's not a p.i.t.a switch on word to fix one typo...). - There are other posts from jalliblog you can use: - series about i2c: http://jallib.blogspot.com/2009/01/step-by-step-building-i2c-slave-with.html, http://jallib.blogspot.com/2009/01/step-by-step-building-i2c-slave-with_17.htmland http://jallib.blogspot.com/2009/01/step-by-step-building-i2c-slave-with_20.html - PWM (for the upcoming section, hope not in Deutch...), showing two main applications: http://jallib.blogspot.com/2009/02/step-by-step-having-fun-with-pwm-and.htmland http://jallib.blogspot.com/2009/02/step-by-step-having-fun-with-pwm-and_14.html It's great to see this happen. As you suggest, we need to decide where we want to go with this, how much details, what should be included, what shouldn't, and most importantly be careful about duplication, particularly when it's about documentation duplication. Cheers, Seb -- Sébastien Lelong http://www.sirloon.net http://sirbot.org 2009/8/16 Joep Suijs <[email protected]> > Hi all, > > We discussed the need of introduction documentation for jallib/jalv2 > on the jallib list. Toon and I made quite some progress on this > subject and since there are similar initiatives on the jalweb list, I > decided to release an early version of the result for review. Please > tell us what you think of this. > > And as for all these initiatives: I think we should have a plan first > on what we need, how we get this and how we mainitain it. Creating > something is easy. Creating something usefull for a broader audiance > is a difficult, since it has to have a suitable form, needs to be > correct and complete (and it would be good to have an introduction and > advanced documentation / reference for the next level). The real hard > thing is to maintain what is created. And this is also the most > important one, otherwise there will be an other dead resource on the > subject, making it more difficult to achieve a decent result in the > future. > > IMHO, the document enclosed could wel become the introduction guide. > It covers most of the subjects, except the language introduction, > hardware and programming (ICSP, bootloader that is). > The exended guide could be based the pjal documentation (which seems > to be ignored, except by sunish) and info from the api documentation > as a reference. The result will be documents, not a flashy site or > colorfull blog. Is that what we want to invest in? If so, we need a > few people contributing and someone who takes the rol of chief > editor... > > 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 -~----------~----~----~----~------~----~------~--~---
