The Unofficial Raspberry Pi Manual

[benzeman]

View the final thing (work in progress): https://www.dropbox.com/s/rkrboq3i7tee64c/final.pdf

Well, as my last exam is on the 21st of June, I thought I'd do something useful over the summer - put together an unofficial raspberry pi manual.

What do people think of the following (proposed) contents: https://www.dropbox.com/s/zmigq6qahgclu ... ntents.pdf

The only thing I'm not sure about is the colour of the Python section. I'm not sure if it's too light - it's a challenge because the colour needs to be dark enough to be readable, light enough so black text is readable on it's background, and it also needs to be far enough from any other colours.

I'm also thinking of adding some more space between the title and the body text - what do you think?

Finally, I have one page spare - what do you think I should do with it? It's page 74 - it's a left hand page, just before "further reading".

Thanks for reading!

Ben

[rsbrowndog]

Morning,

Initial view is that it looks good and I would be very interested in getting my hands on a copy to read and pass on to my son!

Comments...

1) In the Hardware section you list GPIO, Lego NXT and USB Robotic Arm. I was wondering whether a separate "Projects" section towards the end of the book might be a better fit?

2) Speaking as someone who spent the better part of 2 days becoming increasingly frustrated with problem after problem on my Pi which was eventually linked to a rubbish PSU, will you be including "recommended purchases" in the Hardware section?

3) I came to the forum this morning to investigate SD cards and get my head around the different classes and what is/isn't compatible and what impact they have, so a section on SD cards might be an idea?

4) I appreciate that this is probably aimed at people who actually have their hands on a Pi, but what about a section dealing with setting up a VM on your PC to test with?

5) How about a "Troubleshooting" section and/or a "Tweaks" section?

6) Any thoughts on an "Advanced" section that deals with compiling/building software for the Pi?

If I think of anything else I will let you know, but I'm already looking forward to seeing what you come up with!

Cheers,

Ryan

[benzeman]

Morning,

Initial view is that it looks good and I would be very interested in getting my hands on a copy to read and pass on to my son!

Awesome! Glad you like it.

Comments...

1) In the Hardware section you list GPIO, Lego NXT and USB Robotic Arm. I was wondering whether a separate "Projects" section towards the end of the book might be a better fit?

Initially, I think I'm going to keep them under "hardware". For a second edition, as such, I may add a projects section, with all of the above and more. I'd prefer to get a working first edition out, and then update it with a second edition, then never end up actually releasing it because of constant improvements.

2) Speaking as someone who spent the better part of 2 days becoming increasingly frustrated with problem after problem on my Pi which was eventually linked to a rubbish PSU, will you be including "recommended purchases" in the Hardware section?

I will indeed be recommending cases, power supplies, as well as simply listing "working" models.

3) I came to the forum this morning to investigate SD cards and get my head around the different classes and what is/isn't compatible and what impact they have, so a section on SD cards might be an idea?

Hmm, I was going to add that, thought I already did... I have updated the pdf to include this.
EDIT - I'm now going to include this under "Building your SD card".

4) I appreciate that this is probably aimed at people who actually have their hands on a Pi, but what about a section dealing with setting up a VM on your PC to test with?

By the time this is finished you will probably have a Pi - it's not going to be done any time soon - sorry!

5) How about a "Troubleshooting" section and/or a "Tweaks" section?

6) Any thoughts on an "Advanced" section that deals with compiling/building software for the Pi?

See the second half of my response to comment #1

[Robert_M]

Looks pretty good.

The idea to add more space below the title is a good one, especially since there's so much left at the bottom of the page.

As for the color issue, why not adjust the color for "Scratch" instead? I imported the pdf into my photo editing software and grabbed html colors to try a couple things. From "Scratch" I grabbed: #f9b143 and from "Python" I grabbed: #ffda55. After a bit of playing around I came up with this alternate for "Scratch": #ffc087. It looks like it should also work under black text. The idea is to go toward "tan" more than "orange" to help separate the two.

As for the blank page... well, it's a dumb joke for all of us on the forum, but might be worthwhile to include: Two photos, one over the other. The top picture is of an R-Pi. The caption for this picture is: "This is a Raspberry Pi." The bottom picture is of (you guessed it) a Raspberry Pie. The caption for this picture is "This is also a Raspberry Pie. No USB or Ethernet included." As I say, dumb joke, but it would fill the page for ya.

[benzeman]

The idea to add more space below the title is a good one, especially since there's so much left at the bottom of the page.

Done!

As for the color issue, why not adjust the color for "Scratch" instead? I imported the pdf into my photo editing software and grabbed html colors to try a couple things. From "Scratch" I grabbed: #f9b143 and from "Python" I grabbed: #ffda55. After a bit of playing around I came up with this alternate for "Scratch": #ffc087. It looks like it should also work under black text. The idea is to go toward "tan" more than "orange" to help separate the two.

The "Scratch" colour is the official scratch colour, I don't really want to change it if I can avoid it. Also, if for colours we can deal in RGB or CMYK values, that would be great For some reason InDesign won't accept a HEX value.

As for the blank page... well, it's a dumb joke for all of us on the forum, but might be worthwhile to include: Two photos, one over the other. The top picture is of an R-Pi. The caption for this picture is: "This is a Raspberry Pi." The bottom picture is of (you guessed it) a Raspberry Pie. The caption for this picture is "This is also a Raspberry Pie. No USB or Ethernet included." As I say, dumb joke, but it would fill the page for ya.

Love it

[Markavian]

Looks interesting.

Are you interested in contributors to help write sections? I was going to suggest putting the content into a google docs or some other collaborative tool so that people could help write and update the manual.

I think your section coverage is good, some thoughts:

• Instead of "Misc software" have a "package installation" section with a list of possible software to try out.
• A section on media playback in generally, not just XBMC? Mplayer2? Others? Sound support?
• Synergy for mouse and keyboard sharing with an existing PC set up (saves having to buy an extra keyboard/mouse)
• Introduction to other programming languages, like a few sample lines of code for PHP, C++, C, JavaScript, Haxe, etc. and pointers where to go to find more information. Might spark some readers to go off exploring.

I like the format and the colouring. If you're worried about contrast, use the colours as backgrounds to numbered headings, like squares or rectangles that mark the headers, and keep the font black. How about coloured squares filled with with white numbers at each heading? I think the palette you've picked is fine.

Edit: I think GIMP is a terrible piece of software, http://alternativeto.net/software/gimp/?platform=linux - there are alternatives which might provide a better end user experience.

[kirbyman62-2]

My last exam is 21st of June as well, Electronics by any chance?

Looks great, I had a look at the old BBC Micro manuals and it'd be great to replicate them. The empty page could perhaps be an index of important terms?

[benzeman]

Are you interested in contributors to help write sections? I was going to suggest putting the content into a google docs or some other collaborative tool so that people could help write and update the manual.

Send me an email ben [at] beh [dot] me [dot] uk - I'd love to have you on board!

For collaboration we're using dropbox - because I'm using InDesign for layout all you need to do is submit a *.doc or *.txt file, and I can just import it in. Give me pictures too (high-res JPEG), and I'll import them.

I think your section coverage is good, some thoughts:

• Instead of "Misc software" have a "package installation" section with a list of possible software to try out.
• A section on media playback in generally, not just XBMC? Mplayer2? Others? Sound support?
• Synergy for mouse and keyboard sharing with an existing PC set up (saves having to buy an extra keyboard/mouse)
• Introduction to other programming languages, like a few sample lines of code for PHP, C++, C, JavaScript, Haxe, etc. and pointers where to go to find more information. Might spark some readers to go off exploring.

• I'll look into that when writing that page, not sure of the titles for either of the "Misc" pages, but I felt I need them to cover random stuff that people need but they don't realise they need.
• This will go in misc software
• Perhaps in a later edition, for now I just want to get a first edition out into the world.

I like the format and the colouring. If you're worried about contrast, use the colours as backgrounds to numbered headings, like squares or rectangles that mark the headers, and keep the font black. How about coloured squares filled with with white numbers at each heading? I think the palette you've picked is fine.

Thanks very much - I've tried to mimic the style of the last few school magazines I've also done what you suggested about the contents page, much better idea.

Edit: I think GIMP is a terrible piece of software, http://alternativeto.net/software/gimp/?platform=linux - there are alternatives which might provide a better end user experience.

Have adjusted to cover graphics software in general.

My last exam is 21st of June as well, Electronics by any chance?

Yes, did in in year 10 and bot a B and was told I wouldn't be able to get an A so to retake - then it turns out my coursework was (pre-moderation, but we've never been moderated down before) 84/90, so that puts me on an A without retake, so I guess I'm retaking for the A*

The empty page could perhaps be an index of important terms?

Of course - that's a top-notch idea!

I've got a preview of all the pages stitched together, I'll try to update it semi-regularly but progress will be slow until the end of my exams. https://www.dropbox.com/s/rkrboq3i7tee64c/final.pdf

[Robert_M]

The update looks great - and resolves the color issue for Scratch & Python. Well done!

(for some reason, "Scratch & Python" sounds like the Ren & Stimpy of the Pi world...)

[benzeman]

Right, OK:

I'm now looking for two people to write in the "Scratch" and "Python" sections. You'll need to write 6 two page spread each, with screenshots, and release your work under the CC-BY-SA license. I'll give you credit on page 2 (see the OP for an idea of what this will look like).

If you're interested, please drop me an email - ben [at] beh [dot] me [dot] uk.

N.B. - for python, please use python 3.x.

[benzeman]

Also, if anyone who has been following the Raspberry Pi for longer than I have wants to write a two page spread (with pictures, so not two pages in reality) about the "story" of the Raspberry Pi (from Eben's idea in 2006, to release date, and possibly to the first unboxing videos, and Pi's arriving), and would be willing to release it under CC-BY-SA, then that would be greatly appreciated!

I just started trying to write it, and only then realised how little I know about it.

[AndrewS]

Have you been in touch with the MagPi folks? Seems like there's a fair bit of "shared work" that could be done...

[plugwash]

I understand the desire to group things by topic but I think that their needs to be a "getting started" section near the begining that keeps things simple for the newcomer rather than confusing them with 6 different OS options most of which are not yet in a usable state.

[meltwater]

Totally agree, we are happy to share anything useful we produce with the manual.

Also crosses over with the frambozenbier.org community documentation project.
http://elinux.org/RPi_DatasheetCategories

Also there is the official manual itself (I think steered towards schools).
EDIT: In fact see thread, they are also asking for content...
http://www.raspberrypi.org/phpBB3/viewt ... =10&t=5925

Anyway... The project itself is a great idea, and hopefully such a beast can be compiled, even if it takes place gradually. Also, things will tend to evolve over time (the distros in particular, so it can be hard to assume what is in each etc).

We just need the people who find all the linux stuff naturally easy to come give us a hand to explain things for beginners. Even for those who have dabbled in linux, it can be quite a challenge when faced with something which isn't working.

The MagPi team have similar problems, since none of us are linux gurus (as far as I know) we are also learning as we go so it'll take time for us to get up to speed with bending the Raspberry Pi to our will.

There is a lot to learn and to pass on to other users, so all clear and easy to follow information is welcome in whatever form it takes.

[benzeman]

Totally agree, we are happy to share anything useful we produce with the manual.

Great! I assume you and / or your contributors are using the CC-BY-SA licence then?

Also crosses over with the frambozenbier.org community documentation project.
http://elinux.org/RPi_DatasheetCategories

Great - didn't know about this - but it will be very useful - especially as the licence for the wiki has now officially changed to CC-BY-SA!

Also there is the official manual itself (I think steered towards schools).
EDIT: In fact see thread, they are also asking for content...
http://www.raspberrypi.org/phpBB3/viewt ... =10&t=5925

Yeah, I'm aiming my manual more at the average Joe who knows very little about computers (or at least, very little about Linux and ARM), but has just picked up a Raspberry Pi.

[meltwater]

Yeah the licence thing...at the moment I don't think we specify, but hopefully I can get them to pick one.
I see no reason why we won't pick CC-BY-SA, but again it is something I know little about (I'm getting fed up of writing that...I need to read more!).

It is still worth linking with the raspberry filling though, since they will still have to cover similar stuff. No idea what their way of working is though, if it is open to view or not. Hopefully if it was closed (fine when there was no hardware around) they will consider opening it up so beginners can start to use it (unless they intend it to be exclusive to education).

But there is very steep learning curve even for those who have used linux before in passing, so there is a need for it. My concern is two-fold, one there is little point in duplicating work (i.e. multiple setup guides etc etc) and two as the distros change the instructions will change (all the more important to stick with a single guide).

At the moment, doing lots of things on the Rpi mean lots of little work arounds and fixes, this makes a good guide very important, but it also causes a problem for the MagPi format since distros should change and improve this (meaning the guides will become outdated). I guess it needs a little handling of "it should work like this but you may need to do this" type thing.

In some ways, I guess the MagPi is kinda stop-gap, how to use the RPi now, and a manual will be how to use the RPi in general, hopefully with the bugs smoothed out.

[benzeman]

Could somebody move this to the Projects/Magazines & Books section please? Thanks!

[benzeman]

Thank you!

[benzeman]

The official website (for the unofficial manual) is now http://r314.co.uk/

[majormonkey]

Nice domain name !

[benzeman]

Nice domain name !

Haha, thanks! Grabbed it as soon as I heard about the Pi! Just hope it will be OK with the trademark rights!

[benzeman]

Just to say I'm going to send the first newsletter sometime on Thursday...

[benzeman]

What do people think of adding a shopping page, where any retailer which sells stuff for the raspberry pi can feature some of their products?

[parkenator]

This looks very promising. Cant wait until it is finished. Can see it being very helpful

[benzeman]

This looks very promising. Cant wait until it is finished. Can see it being very helpful

Thanks! I've got an IT coursework hand in deadline on Monday, Maths on Wednesday, then ELectronics next week and I'll then be working on this full-time, and hope to finish it by the end of term (20th July).