User avatar
clive
Forum Moderator
Forum Moderator
Posts: 1013
Joined: Tue Feb 07, 2012 8:19 pm

CAS Educational Manual:how to contribute

Thu Jan 03, 2013 11:26 am

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 :)

suzume
Posts: 1
Joined: Fri Jan 04, 2013 2:48 am

Re: CAS Educational Manual:how to contribute

Fri Jan 04, 2013 4:46 am

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 ?

User avatar
recantha2
Posts: 281
Joined: Wed Nov 14, 2012 9:34 am
Location: Potton, Bedfordshire
Contact: Website

Re: CAS Educational Manual:how to contribute

Fri Jan 04, 2013 11:01 am

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.
--
Michael Horne - @recantha
Raspberry Pi blog - http://www.recantha.co.uk/blog

Cambridge Raspberry Jam
Website: http://camjam.me
Facebook: https://www.facebook.com/cambridgeraspberryjam
Follow the Cambridge Raspberry Jam on Twitter - @cambridgejam

User avatar
psergiu
Posts: 223
Joined: Mon Nov 07, 2011 8:36 am
Location: TX, U.S.A. (was: RO, E.U.)
Contact: Website

Re: CAS Educational Manual:how to contribute

Fri Jan 04, 2013 1:00 pm

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.

User avatar
recantha2
Posts: 281
Joined: Wed Nov 14, 2012 9:34 am
Location: Potton, Bedfordshire
Contact: Website

Re: CAS Educational Manual:how to contribute

Fri Jan 04, 2013 1:22 pm

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. :-)
--
Michael Horne - @recantha
Raspberry Pi blog - http://www.recantha.co.uk/blog

Cambridge Raspberry Jam
Website: http://camjam.me
Facebook: https://www.facebook.com/cambridgeraspberryjam
Follow the Cambridge Raspberry Jam on Twitter - @cambridgejam

User avatar
liz
Raspberry Pi Foundation Employee & Forum Moderator
Raspberry Pi Foundation Employee & Forum Moderator
Posts: 5201
Joined: Thu Jul 28, 2011 7:22 pm
Contact: Website

Re: CAS Educational Manual:how to contribute

Fri Jan 04, 2013 1:39 pm

That's awesome - thanks Recantha. We do appreciate that turning it into a Kindle version means a lot of work; thanks again!
Director of Communications, Raspberry Pi

feiry
Posts: 11
Joined: Fri Jan 04, 2013 2:08 pm
Location: Bandung, Indonesia
Contact: Website

Re: CAS Educational Manual:how to contribute

Fri Jan 04, 2013 2:53 pm

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!

User avatar
clive
Forum Moderator
Forum Moderator
Posts: 1013
Joined: Tue Feb 07, 2012 8:19 pm

Re: CAS Educational Manual:how to contribute

Fri Jan 04, 2013 3:01 pm

Hi feiry - I've PMd you. Note you can now PM too after that one post :)

User avatar
Jim Manley
Posts: 1600
Joined: Thu Feb 23, 2012 8:41 pm
Location: SillyCon Valley, California, and Powell, Wyoming, USA, plus The Universe
Contact: Website

Re: CAS Educational Manual:how to contribute

Fri Jan 04, 2013 3:17 pm

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?
The best things in life aren't things ... but, a Pi comes pretty darned close! :D
"Education is not the filling of a pail, but the lighting of a fire." -- W.B. Yeats
In theory, theory & practice are the same - in practice, they aren't!!!

BobCochran
Posts: 27
Joined: Sat Dec 29, 2012 2:51 am
Location: Greenbelt, Maryland, USA

Re: CAS Educational Manual:how to contribute

Sat Jan 05, 2013 4:22 am

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

User avatar
Jim Manley
Posts: 1600
Joined: Thu Feb 23, 2012 8:41 pm
Location: SillyCon Valley, California, and Powell, Wyoming, USA, plus The Universe
Contact: Website

Re: CAS Educational Manual:how to contribute

Sat Jan 05, 2013 10:36 am

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 ;)
The best things in life aren't things ... but, a Pi comes pretty darned close! :D
"Education is not the filling of a pail, but the lighting of a fire." -- W.B. Yeats
In theory, theory & practice are the same - in practice, they aren't!!!

skatt
Posts: 1
Joined: Sat Jan 05, 2013 10:36 pm

Re: CAS Educational Manual:how to contribute

Sat Jan 05, 2013 11:12 pm

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

User avatar
clive
Forum Moderator
Forum Moderator
Posts: 1013
Joined: Tue Feb 07, 2012 8:19 pm

Re: CAS Educational Manual:how to contribute

Sun Jan 06, 2013 12:31 am

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.

User avatar
clive
Forum Moderator
Forum Moderator
Posts: 1013
Joined: Tue Feb 07, 2012 8:19 pm

Re: CAS Educational Manual:how to contribute

Sun Jan 06, 2013 12:33 am

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

feiry
Posts: 11
Joined: Fri Jan 04, 2013 2:08 pm
Location: Bandung, Indonesia
Contact: Website

Re: CAS Educational Manual:how to contribute

Sun Jan 06, 2013 1:18 am

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.

User avatar
psergiu
Posts: 223
Joined: Mon Nov 07, 2011 8:36 am
Location: TX, U.S.A. (was: RO, E.U.)
Contact: Website

Re: CAS Educational Manual:how to contribute

Wed Jan 09, 2013 3:06 pm

Just a note.
The manual files cannot be opened with the "free" InDesign CS2 Adobe just made available - a newer InDesign version is needed.

User avatar
Jim Manley
Posts: 1600
Joined: Thu Feb 23, 2012 8:41 pm
Location: SillyCon Valley, California, and Powell, Wyoming, USA, plus The Universe
Contact: Website

Re: CAS Educational Manual:how to contribute

Sun Jan 13, 2013 12:30 am

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
The best things in life aren't things ... but, a Pi comes pretty darned close! :D
"Education is not the filling of a pail, but the lighting of a fire." -- W.B. Yeats
In theory, theory & practice are the same - in practice, they aren't!!!

pygmy_giant
Posts: 1562
Joined: Sun Mar 04, 2012 12:49 am

Re: CAS Educational Manual:how to contribute

Sun Jan 13, 2013 1:33 am

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.

pygmy_giant
Posts: 1562
Joined: Sun Mar 04, 2012 12:49 am

Re: CAS Educational Manual:how to contribute

Sun Jan 13, 2013 12:07 pm

@ 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!

feiry
Posts: 11
Joined: Fri Jan 04, 2013 2:08 pm
Location: Bandung, Indonesia
Contact: Website

Re: CAS Educational Manual:how to contribute

Wed Jan 16, 2013 7:43 am

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!

User avatar
Jim Manley
Posts: 1600
Joined: Thu Feb 23, 2012 8:41 pm
Location: SillyCon Valley, California, and Powell, Wyoming, USA, plus The Universe
Contact: Website

Re: CAS Educational Manual:how to contribute

Wed Jan 16, 2013 8:37 am

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).
The best things in life aren't things ... but, a Pi comes pretty darned close! :D
"Education is not the filling of a pail, but the lighting of a fire." -- W.B. Yeats
In theory, theory & practice are the same - in practice, they aren't!!!

feiry
Posts: 11
Joined: Fri Jan 04, 2013 2:08 pm
Location: Bandung, Indonesia
Contact: Website

Re: CAS Educational Manual:how to contribute

Wed Jan 16, 2013 10:00 am

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.

feiry
Posts: 11
Joined: Fri Jan 04, 2013 2:08 pm
Location: Bandung, Indonesia
Contact: Website

Re: CAS Educational Manual:how to contribute

Wed Jan 16, 2013 10:08 am

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.

User avatar
Jim Manley
Posts: 1600
Joined: Thu Feb 23, 2012 8:41 pm
Location: SillyCon Valley, California, and Powell, Wyoming, USA, plus The Universe
Contact: Website

Re: CAS Educational Manual:how to contribute

Fri Jan 18, 2013 8:58 am

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!"
The best things in life aren't things ... but, a Pi comes pretty darned close! :D
"Education is not the filling of a pail, but the lighting of a fire." -- W.B. Yeats
In theory, theory & practice are the same - in practice, they aren't!!!

User avatar
clive
Forum Moderator
Forum Moderator
Posts: 1013
Joined: Tue Feb 07, 2012 8:19 pm

Re: CAS Educational Manual:how to contribute

Mon Jan 21, 2013 10:47 am

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!

Return to “Teaching and learning resources”