Page 1 of 2

CAS Educational Manual:how to contribute

Posted: Thu Jan 03, 2013 11:26 am
by clive
Note: The Raspberry Pi Educational Manual is not a Raspberry Pi Foundation product.

It is solely the work of Computing at School. Obviously, we think it's great: it's free, community-made and teaches you how to use your Raspberry Pi for lots of different things. But it is not made or maintained by the Foundation.

Now that's out of the way, there does seem to be a need for a place to discuss the manual on these forums. I will point the CAS group here, but it's unlikely that any changes will be made by them in the short term (for one thing, we've been working on it for a year and are glad to see the back of it for a while :)) If you want to talk to CAS direct their forums are here.

Translations
Please start a new thread for each language, where collaborators can organise and discuss that particular translation. I have the source files for the manual (InDesign) -- PM me if you want these. (I'll upload them somewhere when I get a chance)

Errata
Please post errors and omissions etc in the errata thread. Be clear and concise and refer to page numbers and paragraphs. Make specific suggestions for change, not just say something is wrong or missing. E.g. "P23, para 2, 1st sentence: "welcomoe" should be "welcome".

Comments and suggestions
Are welcome! Do bear in mind that the licence (CC BY-SA-NC) allows you to adapt and change (improve!) the manual, so if you have a good idea or something to add then feel free! Or just post below :)

As usual, thanks to everyone for their input on this. The manual is already a great resource but based on the feedback we've already had I'm sure that it will get even better :)

Re: CAS Educational Manual:how to contribute

Posted: Fri Jan 04, 2013 4:46 am
by suzume
If the source format is proprietary (InDesign) then it will be very hard to modify the original document or even to translate it.

Since InDesign data is not easily converted to anything workable (like Scribus format for ex), it seems to me a good first step would be to convert the document to such a format and then to consider modifications/translations.

What do you think ?

Re: CAS Educational Manual:how to contribute

Posted: Fri Jan 04, 2013 11:01 am
by recantha2
Suzume, I agree - access to the original source files is, I believe, the only way to contribute to this without corrupting the original idea and layout of the book. I also think that this would be the only way to reliably do other versions, such as HTML or Kindle versions, without introducing formatting or grammatical errors.

One suggestion I would have is that after the introduction there is no instruction on how to get from switching the Pi on to the Scratch interface. Even if it's just a one-page "What to do when your Pi starts up" and "What is all this gobbledeegook I can see on the screen?", it would help to get students from the login prompt to X windows and scratch.

Re: CAS Educational Manual:how to contribute

Posted: Fri Jan 04, 2013 1:00 pm
by psergiu
I asked my DTP-savvy friends how can this document be translated by people without access to InDesign.

There are three ways:
1) The hard way:
- Person with access to InDesign exports document as text-only;
- Translators translate said text using UTF8 text editor of choice;
- Person with access to InDesign copy-pastes translated text back in document and reflows as needed (assuming he can at least partially understand the translated text so he can see which translated paragraph corresponds to which english one)

2) The harder way:
- Person with access to InDesign assigns Tags to each and every paragraph in the document then exports as XML;
- Translators translate text inside XML file using UTF8 text editor of choice being careful to not remove/alter the XML markup;
- Person with access to InDesign imports translated XML file then reflows the document if needed.

3) The costly way:
- Person with access to InDesign buys Copy Flow Gold ( http://www.napsys.com/CFGInDesignCS6.html ) and exports the document as text-only with formatting tags;
- Translators translate said text using UTF8 text editor of choice being careful to not remove/alter the CopyFlowGold formatting tags;
- Person with access to InDesign uses CopyFlowGold to import the translated text with a single click then reflows the document if needed.

Re: CAS Educational Manual:how to contribute

Posted: Fri Jan 04, 2013 1:22 pm
by recantha2
Thanks for the files, Clive. The Kindle version is under way. Might take me a little while - a lot of the formatting needs to come out and be respecified. The good news is that when I'm finished I'll have an HTML version as well. :-)

Re: CAS Educational Manual:how to contribute

Posted: Fri Jan 04, 2013 1:39 pm
by liz
That's awesome - thanks Recantha. We do appreciate that turning it into a Kindle version means a lot of work; thanks again!

Re: CAS Educational Manual:how to contribute

Posted: Fri Jan 04, 2013 2:53 pm
by feiry
Hi Clive,

I want to translate the Educational Manual to Indonesia.
Sorry I can't PM you, because I am new to the forum.

Can you send me the InDesign file, I can download the trial version of Adobe InDesign to modify it.
So I can give it to my students (currently voluntarily teaching kids age 9-12 at SOS Kinderdorf Lembang-Bandung, Indonesia. http://www.sos-childrensvillages.org).

I just get my Raspberry Pi 2 weeks ago and can't wait to show to the kids.

I am currently teach them Scratch on their windows computer lab. It's my first project.
I have a plan to teach the poor street kids computer science with the Raspberry Pi when I am ready.
Because there is no computer labs on the street. :D

Thanks!

Re: CAS Educational Manual:how to contribute

Posted: Fri Jan 04, 2013 3:01 pm
by clive
Hi feiry - I've PMd you. Note you can now PM too after that one post :)

Re: CAS Educational Manual:how to contribute

Posted: Fri Jan 04, 2013 3:17 pm
by Jim Manley
I originally posted a variation of the following as a comment to Liz's post of Dr. Andrew Robinson's announcement of the availability of the Educational Manual. I've added some more thoughts after them in order to help get this idea off the ground.

I was thinking that a wiki version would actually be more useful than just HTML (as suggested in a response to Liz's/Andrew's announcement post) in that it would make it much easier for contributors to enhance and expand the content. Yes, I realize how much of a double-edged sword that can be, but with wikis’ built-in version control and contributor access management (if needed), the potential for crazies making a mess of things can be kept to a dull roar. Since most wiki formats support at least partial HTML features, that would provide the means for controlling presentation adequately.

This would mean hosting the wiki version on an appropriately-configured server (e.g., a WikiMedia server - there are other options). There are free wiki hosting sites that have varying levels of advertising, but the manual is small enough that it might be able to be hosted on a free, non-ad-supported site, such as WikiDot.org, which is hosted on Amazon.com commercial-grade EC2 web servers that are replication-distributed across the Internet and automagically backed up. I've started to set up an example of what this could look like at http://cas-pi-education-manual.wikidot.com . There seems to be something weird about the public access control as I set it up to control who can edit it, so you may not be able to get to the wiki until I get that ironed out later today.

I believe Clive mentioned that the original source material is in inDesign file(s), but it’s not clear whether they’re publicly available, or whether it’s expected that a PDF editor will be used by those wishing to contribute. It’s also not obvious how version control would be established if files are edited. Are contributors supposed to make edited PDFs available and the official CAS version will be updated by its originators as they see fit?

Re: CAS Educational Manual:how to contribute

Posted: Sat Jan 05, 2013 4:22 am
by BobCochran
How many illustrations did Helen Ireland do? I so wish there were more from her. I find the illustration at the start of the book to be very appealing. More illustrations would really add to the book.

Bob

Re: CAS Educational Manual:how to contribute

Posted: Sat Jan 05, 2013 10:36 am
by Jim Manley
Would it be possible to obtain the original images in the manual so that I can put them in the wiki? For some reason, the front cover artwork can't be selected for copying in Adobe Reader, and there may be other images elsewhere in the document that I can't extract easily, either.

Also, the details in the highly-compressed images in the PDF are nearly completely obliterated and totally unreadable. This needs to be fixed in the PDF anyway, as the images of the screen shots in particular are virtually worthless. I understand that they may only be meant to show representative overviews of various screen states, but I think this is shortsighted if that's the case. Screenshots should display as much detail as possible, even if it means the size of the manual is going to increase substantially. I'm a little bit surprised that this wasn't immediately realized by the educators involved in production/review of this otherwise very nicely-written manual.

One other nit - there are places where the author refers to themselves as "I", and other places where the "royal we" is invoked. I believe that the "royal we" should be used consistently throughout the manual, given that it's a collaborative effort, even if particular sections or even entire chapters were written by one person.

Oh, and do a search for "horizontal" line, which should read "vertical" in the reference to the Unix/Linux "pipe" character. I'm sure the author was feeling a need to be horizontal by the time they got to that part of the writing, but naive readers will be puzzled at least momentarily ;)

Re: CAS Educational Manual:how to contribute

Posted: Sat Jan 05, 2013 11:12 pm
by skatt
Clive,

did i get it right that there must be a translation forum on this site? I can't manage to find it.

Regards,
Skatt

Re: CAS Educational Manual:how to contribute

Posted: Sun Jan 06, 2013 12:31 am
by clive
BobCochran wrote:How many illustrations did Helen Ireland do? I so wish there were more from her. I find the illustration at the start of the book to be very appealing. More illustrations would really add to the book.

Bob
Just that one. We agree that more illusratiuons and graphics would be good but it's all amatter of time and resources.

Re: CAS Educational Manual:how to contribute

Posted: Sun Jan 06, 2013 12:33 am
by clive
skatt wrote:Clive,

did i get it right that there must be a translation forum on this site? I can't manage to find it.

Regards,
Skatt
We've asked that a new thread is started for each translation so that those working on it have a place to organise and collaborate

Re: CAS Educational Manual:how to contribute

Posted: Sun Jan 06, 2013 1:18 am
by feiry
I am currently working on Indonesian Translation.
If anybody want to help or collaborate, I will open a new thread.

I am afraid I am alone right now. :)

Just let me know if anybody wants to help.

Re: CAS Educational Manual:how to contribute

Posted: Wed Jan 09, 2013 3:06 pm
by psergiu
Just a note.
The manual files cannot be opened with the "free" InDesign CS2 Adobe just made available - a newer InDesign version is needed.

Re: CAS Educational Manual:how to contribute

Posted: Sun Jan 13, 2013 12:30 am
by Jim Manley
I'm still looking for full-resolution screenshot images where the content is readable as the PDF document compresses some of them to the point of illegibility. Also, some images, such as the very first one for the cover, can't be extracted by selection and copying. Any help in obtaining full-resolution images for the wiki version would be greatly appreciated.

Can someone tell me whether they can at least read the wiki pages at:

http://cas-pi-education-manual.wikidot.com

Re: CAS Educational Manual:how to contribute

Posted: Sun Jan 13, 2013 1:33 am
by pygmy_giant
If the InDesign document is set up properly, the text should be in a seperate word or .txt file which anyone can edit, but InDesign is required to alter/tweak the layout and to produce the .pdf document.

I've got InDesign CS4 - I would be happy to assist with any of that if needed.

If CS2 is now free, it might not be a bad idea to convert it to thet CS2 format.

Adobe build in compatability for one product revision by using the .INX format, so, a document produced in CS4 can be converted to CS2 by exporting it to the .INX format, opening that in CS3, exporting again as .INX before finally opening in CS2. I think the latest version is CS6.

Obviously the additional features of the newer version of their software won't work in the older version, but if its a basic document it should look pretty much, if not exactly, the same.

Backwards compatability is no problem, but once you open a document produced in an old CS version on a newer CS version of their InDesign softwware and save it again - thats it - you've tied it down to that newer version, or higher.

It therefore does make some sense if being modest with your razzle-dazzle to use an old version for editing if you intend other people to be able to edit the layout / re-export to .pdf. Conversely the other option is to join the CS version arms race and boost Adobe's profits.

Re: CAS Educational Manual:how to contribute

Posted: Sun Jan 13, 2013 12:07 pm
by pygmy_giant
@ Jim - I can read the wiki - but whats the link to the .pdf?

Edit: oh- iths here: http://downloads.raspberrypi.org/Raspbe ... Manual.pdf

views ok on my windows pc although a few of the pictures in it are very pixlated - too much jpeg compression? Functionally speaking the text in those screen shots is unreadable - as a result page 22 is useless as you cannot read the scratch code. Big problem.

Theres a task for someone - re-capture/re-compress some higher quality screen shots of the dodgy pics to re-insert - unless of course this is to do with the settings used when exporting the document to .pdf which would be easier to fix.

Otherwise to me it looks clear and instructive. I would use this manual myself to get my son using scratch if it were not for the pixlation!

Re: CAS Educational Manual:how to contribute

Posted: Wed Jan 16, 2013 7:43 am
by feiry
Hi Folks,

I found some mistakes during my translation to Indonesian languange.
How to tell the original authors, so they can fix the manual?

Thanks!

Re: CAS Educational Manual:how to contribute

Posted: Wed Jan 16, 2013 8:37 am
by Jim Manley
pygmy_giant wrote:@ Jim - I can read the wiki
Thanks for checking, @pygmy (or is it @mr._giant? ;) ).
pygmy_giant wrote:views ok on my windows pc although a few of the pictures in it are very pixlated

Theres a task for someone - re-capture/re-compress some higher quality screen shots of the dodgy pics to re-insert - unless of course this is to do with the settings used when exporting the document to .pdf which would be easier to fix.
The recapture of the screen shots should be unnecessary, as I assume that the authors still have the original captures. I'm sure they just need to be (much) less compressed. No one has 'fessed up yet, though. Very strange.
pygmy_giant wrote:Otherwise to me it looks clear and instructive. I would use this manual myself to get my son using scratch if it were not for the pixlation!
Note that the wiki is currently just the text with almost none of the formatting, which I plan to update. I've already been able to reproduce the layout of the title page of the PDF via HTML and CSS, but the stupid wiki seems to have eaten it (I think it's in the revision queue and I should be able to extract it back to the top of the heap). Once I've got one section formatted, it should be fairly straightforward for a bunch of us to each apply the formatting to the subsequent sections (~180 pages of formatting would literally take me six months, given it took the better part of a day to do one page, and the amount of time I don't have to dedicate to this project).

Re: CAS Educational Manual:how to contribute

Posted: Wed Jan 16, 2013 10:00 am
by feiry
Hi Jim,

I have the Adobe InDesign files. All the images, is not like what you see in the pdf files.
All of them just a full screenshot, that you need to crop one by one manually to put it in your wiki.
So it's not just a simple task upload all the images and add the links in the wiki.

Maybe you should pm clive to send you the link to the Adobe InDesign files. You can get all the images without the need to open the InDesign files. But As I said earlier, you still need to find the image and crop it (the image is not cropped yet, it's a screenshot images).
Theres a task for someone - re-capture/re-compress some higher quality screen shots of the dodgy pics to re-insert - unless of course this is to do with the settings used when exporting the document to .pdf which would be easier to fix.
The recapture of the screen shots should be unnecessary, as I assume that the authors still have the original captures. I'm sure they just need to be (much) less compressed. No one has 'fessed up yet, though. Very strange.

Re: CAS Educational Manual:how to contribute

Posted: Wed Jan 16, 2013 10:08 am
by feiry
Hi pygmy_giant,

You can download all the scratch project files from this link: http://goo.gl/MpHUv
It's in the Chapter 1 (page 7), so you can see the actual script clearly.
views ok on my windows pc although a few of the pictures in it are very pixlated - too much jpeg compression? Functionally speaking the text in those screen shots is unreadable - as a result page 22 is useless as you cannot read the scratch code. Big problem.

Re: CAS Educational Manual:how to contribute

Posted: Fri Jan 18, 2013 8:58 am
by Jim Manley
feiry wrote:I have the Adobe InDesign files. All the images, is not like what you see in the pdf files. All of them just a full screenshot, that you need to crop one by one manually to put it in your wiki. So it's not just a simple task upload all the images and add the links in the wiki.
That's fine, I'm a pilot and I do cropdusting ;)
feiry wrote:Maybe you should pm clive to send you the link to the Adobe InDesign files. You can get all the images without the need to open the InDesign files. But As I said earlier, you still need to find the image and crop it (the image is not cropped yet, it's a screenshot images).
I already PMed Clive about five days ago, but still no joy. I'm sure he has much more important things to do than respond to my begging, and I can be patient. Cue the Gary Larson "The Far Side" comic panel, with two vultures sitting on a branch of a long-parched tree, ogling some poor soul crawling across the desert in their direction - and one vulture says to the other, "Patience, my a$$, I'm gonna kill something!"

Re: CAS Educational Manual:how to contribute

Posted: Mon Jan 21, 2013 10:47 am
by clive
Hi Jim -- I had a lot of requests for source files etc so sorry if I missed you! I've send a PM.

While I'm here: thanks to everyone working on this, it is appreciated!