On Wed, 26 Oct 2005, Beni Cherniavsky wrote: > On Sun, 2005-10-23 at 04:33 +0200, guy keren wrote: > > the current things i could be helped with are: > > > First, how do we work?
you say "i am going to work on this thing". you take what is found currently, you write it, then you post it. > * Is the HTML hand-written or is it generated from something else? > What do we send patches against? i concentrated on the material, rather then on formatting. i just wrote HTML (ofcourse it is hand-written - i never use HTML editors, and i didn't use any pre-processor in this case). please note that this is not software - it's documentation for a teaching course. as such, it should have a very strict style, and be very coherent. thus, i don't want each item to be edited by several people. there should be one, single editor for each item, and comments may be sent to that person. e.g. i am writing the mini-book, and i don't expect anyone else to _write_ it. i will take comments i am given here about it, and edit them into the book, and update it on my temp. site. someone will take the reference document, and work on it from start to finish, taking small chunks form people who want to contribute them and edit them so it all looks as if it was written by a single person. this is crucial - this is not software, where what people see is the output of the program - here, the source _is_ the output. > * I think working with plain text source is most convenient for > discussions & patches over mail. http://docutils.sf.net or > similar can convert it to nice HTML. if you want to learn those systems and use them - go ahead. i don't have time to start evaluating such systems right now. > * Could you put it on some public version control?It will simplify > keeping updated and managing changes. sorry - no time to mess with such a system and manage it. since i expect a single editor for each item - then i assume the editor will publish the "most updated copy" on a web page, and people will send them comments/document snippets for hand-editing. you can't patch it like you patch software - at least that's what i think. > * If not, please use this mailing list as a changelog and bump the > version numbers on every change. i bump the versoin numbers on the documents i place on the web site. i do not publish the material here directly - i only send links here, and run comments and discussions here. > * Alternatively, you could answer the above two points by putting it on > a wiki. Up to you -- depends whether you like wiki style of work... a wiki is not good for publishing coherent documents, in my opinion. it is useful when you want to write a knowledge-base. > I can hack an html2wiki for the transfer; it can be converted back > when we are done if needed. > > * The Python-IL mediawiki is not quite hebrew-friendly at present. > Putting up a small moinmoin sounds like best approach to me. > Nir, what's your advice? > > * Licensing: you still haven't decided, right? if someone can find a good license that will cover what i originaly talked about - i'll be happy to use it. i'll repeat - the study plan (along with its reference material) should be very open - for everyone to do anything with it. BSD-tyle license? is there something like this that suites documentation? i don't know. the mini-book should be free for use in any way - i don't know yet about free for editing. unlike the study plan, which i expect to be very fluid and adapted to suite the teacher of such a course, the mini-book is a more "closed" and complete work - and it is very easy to ruin such work by non-coherent editing. also, because this mini-book represents much more work, i'd rather have it under a GPL-like license - i.e. the source must be given together with the thing, even if it is a printed book that's being sold for a hefty price, and any changes made to it must be published to anyone who's given the "binary" (printed book, pdf, whatever) file. i understood the GFDL has some problems - is there some license that overcomes these problems? what license do the debian people use for mini-books? what license is used by the guides of the LDP? > > 1. taking the "reference book" i wrote and finish writing it. > > > I can do that, or at least a big part of it (I'll raise a red flag next > week if I need help). ok. i'll await your input (including re-formatting it to use the interactive prompt style you suggested in a previous email ;) ). > > 2. suggesting a better layout for the reference book, so it can be: > > 1. easily browsable on the net. > > 2. easy to print. > > and then implementing this layout. > > > Layout depends on tools we work with.I can take this. Anyway it's not > first priority. right. please concentrate on #1 first. > BTW, is the plan useful at all as a separate document?Currently it's > a fat subset of the reference, I think we can dump the plan and only > work on the reference.We can extract the plan later (or automatically > at any point) ifit's useful. it's the other way around. the plan was written. then what i did was copy the plan file and rename the copy to "reference". then i started editing it, and replaced each "new material" lesson with a section in the reference. what you see there is that i have 6-7 sections that are already in reference format - and then rest is the copy of the original plan, waiting to be replaced. > > 3. checking the existing part of the mini-book for correctness, from a > > programming point of view (not proof-reading the english and clarity - > > that will come once the material is there). > > > Separate mails... ok, still waiting. so far i got some philosphical arguments with nir about how i introduce the material. once this settles down, it'll be used in various parts of the text. > > 4. coming up with ideas for exersizes during the practice meetings, that > > are still marked as "TODO" in the meetings plan. > > > I would like you to elaborate some of the points in the plan -- I'm not > sure what do you mean so I can't help there. since you didn't tell what you want me to elaborate - i can't elaborate :0 i will only be able to get back to this once i have more pressing matters finished - such as slides for the first few lectures... we intend to have the first meeting on november 6th (or one week later, at most). -- guy "For world domination - press 1, or dial 0, and please hold, for the creator." -- nob o. dy
