Ensuring docs and tutorials are kept newbie-friendly


21 posts
by DemonJim » Wed Jun 27, 2012 3:34 pm
One very important thing I would say regarding making the RasPi noob-friendly is to ensure that as it evolves that any documentation out there is updated to reflect these changes. Having out-of-date documentation and tutorials will actually be detrimental to the progress people make.

I envisage people in future watching tutorial vids or following fan-made guides based on these early distro's and getting frustrated wondering why things don't work the same. Any frustration will inevitably see some people giving up, which is the last thing we want to happen.

The key thing for the Pi is that it needs to be the most noob-friendly computer out there.

Btw I'm not referring to the official documentation like on here or on the Wiki (which will naturally always be kept up to date thanks to the awesome dedication of the Foundation), but all the user-made YouTube tutorials, fan-made magazines etc. etc. A good example for this is The MagPi magazine - this is utterly fantastic and I'm in no way criticising them, but some features in these first editions may no longer be applicable in the future, say when the Pi gets its proper case, or there's a PCB design change, or when a totally new Linux distro becomes default.

It is easy for those closely involved with the Pi and those of us following from the beginning to know what is old advice, what is relevant etc., but a total newbie starting out in 12 months time will probably have a baffling array of irrelevant advice on the internet to filter out.

When someone is on their tenth Google search to find an answer to a simple question that still yields out-of date advice and countless forum replies saying 'sigh, this is really easy to Google' will have them confining the Pi to the drawer, which as I say is the very last thing we want kids to do.
DemonStudios Ltd | Indie Game Developer | www.demonstudios.com
User avatar
Posts: 20
Joined: Thu Sep 01, 2011 2:19 pm
Location: UK
by alexeames » Wed Jun 27, 2012 4:18 pm
Very good idea, but with so many private blogs, it's going to be hard to achieve it. Even Wikis aren't always up to date. Also, the more blog articles people write, the harder it will be to keep them up to date. Since my blog is aimed at giving comprehensive instructions based on full walk-throughs of the procedure, I wonder how easy it will be to keep it up to date when there's 50 or 100 articles up there? It's a challenge, but blog posts have dates on them and it's a very good idea to mention what version of which OS we're talking about.

Linus thinks that even if a lot of Pis will end up in drawers, if some programmers come out of it, it will have been worthwhile. I would love to think that more won't end up in drawers than will. For me personally, it's already been worthwhile. :D
Alex Eames RasPi.TV HDMIPi.com RasP.iO
User avatar
Posts: 2054
Joined: Sat Mar 03, 2012 11:57 am
Location: UK
by cashaw » Wed Jun 27, 2012 7:59 pm
My own suggestion on the Foundation hosting easy-get-started guides got deleted without a response, but I agree totally. My experience in learning how to use the Pi involves going to Google and entering "Raspberry Pi <how do I do this>" and the results come from various sources, some of which are aimed at the newbie and others are far too technical.

I know there are Wiki's for the RPi, but they don't seem to be visible from the front page of the Foundations home page.

Here is a suggestion from the makers of my Excito B3 ARM NAS where they have produced a Wiki which nicely suggests small projects or tasks aimed at the beginner, intermediate or advanced user -

http://wiki.excito.org/wiki/index.php/T ... nd_How-tos

It would be great for the foundation to host a similar 'certified' information source rather than rely on us having to search HOW-TO's via Google. I am also waiting to see what educational support the foundation may be providing. Each RPi is contributing to the charity, but I would like to understand how they are using their income and what support is being provided to education rather than a charity just supporting us hackers.

(This is just a suggestion, I am not meaning to upset anyone)
Posts: 71
Joined: Tue Mar 06, 2012 8:32 pm
by jamesh » Wed Jun 27, 2012 8:10 pm
The general problem is that the Foundation founders list consists of about 7 people with full time jobs. It employs one person - who is not responsible for documentation. So there is a massive reliance of volunteer/community work, which in turn means doing the stuff listed above is very difficult.

I agree that documentation is key, but I don't know what to suggest to get over the lack of 'official' manpower. Almost every suggestion made, good or bad, requires more manpower than the Foundation actually has.
Soon to be unemployed software engineer currently specialising in camera drivers and frameworks, but can put mind to most embedded tasks. Got a job in N.Cambridge or surroundings? I'm interested!
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 11583
Joined: Sat Jul 30, 2011 7:41 pm
by cashaw » Wed Jun 27, 2012 8:23 pm
Yes, but with each Pi sold, there is money going into the charity's coffers so it would be good to know the plans on how this is planned to be used.

It would be great to see some news items on the front page where the Foundation can demonstrate what they have been able to achieve so far. Most of the information is about what others have been able to achieve independently from the foundation.

Let's have some success stories which can demonstrate how the foundation has been able improve the teaching of computing in UK Schools. (or at least a plan of action) What is the roadmap for the foundations activities ? The releasing of the hardware platform was (I believe) always secondary to the wish to improve the teaching of computers in schools and the Pi was a means to an end.

It's outside the scope of the foundations remit, but I would be interested in learning if the Government and Education authorities support what the foundation is trying to achieve and if the foundation is lobbying them.
Last edited by cashaw on Wed Jun 27, 2012 8:34 pm, edited 1 time in total.
Posts: 71
Joined: Tue Mar 06, 2012 8:32 pm
by jamesh » Wed Jun 27, 2012 8:34 pm
There's not a lot of profit per board sold - but the unexpectedly large volumes mean there is cash there. However, each Pi sold would probably pay for about 10 minutes of someone's employment......(complete estimate - I don't know exact figures). And please remember, most Foundation members have day jobs...so time is also very short.
Soon to be unemployed software engineer currently specialising in camera drivers and frameworks, but can put mind to most embedded tasks. Got a job in N.Cambridge or surroundings? I'm interested!
Raspberry Pi Engineer & Forum Moderator
Raspberry Pi Engineer & Forum Moderator
Posts: 11583
Joined: Sat Jul 30, 2011 7:41 pm
by cashaw » Wed Jun 27, 2012 8:42 pm
You miss my point, I understand all that but as Liz and Eben travel abroad to yet another trade show, I am still missing the roadmap of how the aim to re-introduce computer science education back into schools is progressing.

And please don't take this as criticism, I am sure the foundation has a solid roadmap and goals in regards to all of this.

But going back to the original point of this topic, it would be great to see a single, certified source of information and tutorials for the RPi which could be approved and supported by the foundation and it's members, similar to the community hosted link which I pointed at in my first reply. It would help reduce my ever increasing RPi bookmark folder :D
Posts: 71
Joined: Tue Mar 06, 2012 8:32 pm
by DemonJim » Wed Jun 27, 2012 8:58 pm
I suppose something that would help is if there was a FAQ here for people who create their own video guides and tutorials, with a view to giving a more consistent experience for the people who try them out.

It could state that they should make it clear which board revision they are using, which distro version is being used etc., and maybe have a standard disclaimer that hardware and software are subject to change so certain aspects may no longer be applicable.

It could go further and have special standard icons or a table template for how to list the hardware and distro used and which hw revisions and distros the guide should work for. Then as new revisions / distros come out, the author can choose to update this table or add icons to confirm to a newbie immediately when they view it that the guide applies to their setup.

It may appear to be stating to obvious giving such disclaimers, or for example, stating that a guide on using sudo is relevant to all the Linux distros, but these are only obvious to those in the know. And the Pi is mainly aimed at those not in the know.

So my advice to people making guides and tutorials is this: please don't be afraid to state the obvious, and if it assumes the reader has any prior knowledge, at all, then always give links to where they can find it out.
DemonStudios Ltd | Indie Game Developer | www.demonstudios.com
User avatar
Posts: 20
Joined: Thu Sep 01, 2011 2:19 pm
Location: UK
by DemonJim » Wed Jun 27, 2012 9:16 pm
Incidentally on the topic of the very limited profit that the foundation makes, may I suggest that it would benefit everyone if the Model B board was therefore actually made more expensive.

Then the Foundation could employ more people, even if just one or two more people, to streamline vital aspects such as documentation.

The Model A board should be kept cheap of course, if not made even cheaper than is already planned to be, and even have it subsidised by the B board (the ones sold in the developed world at least).

Perhaps just like the BBC Micro which gave the Model A and B naming convention there could eventually be an even cheaper Raspberry Pi Electron!
DemonStudios Ltd | Indie Game Developer | www.demonstudios.com
User avatar
Posts: 20
Joined: Thu Sep 01, 2011 2:19 pm
Location: UK
by DemonJim » Wed Jun 27, 2012 9:25 pm
Oh, and further to my previous post, please allow me to put my preorder in now for a Raspberry Pi Archimedes. Thanks in advance ;-)
DemonStudios Ltd | Indie Game Developer | www.demonstudios.com
User avatar
Posts: 20
Joined: Thu Sep 01, 2011 2:19 pm
Location: UK
by alexeames » Wed Jun 27, 2012 9:28 pm
DemonJim wrote:Incidentally on the topic of the very limited profit that the foundation makes, may I suggest that it would benefit everyone if the Model B board was therefore actually made more expensive.


I believe the price is contractually fixed. I think your FAQ idea was a better and more realistic one. So let's assemble it in this thread (or start another) and then maybe it will be used if it's good.
Alex Eames RasPi.TV HDMIPi.com RasP.iO
User avatar
Posts: 2054
Joined: Sat Mar 03, 2012 11:57 am
Location: UK
by AndrewS » Thu Jun 28, 2012 1:29 pm
Isn't this pretty much what you're asking for / suggesting
http://elinux.org/R-Pi_Hub#Projects.2C_ ... _Tutorials :?:

(I believe the wiki is primarily updated by the community, rather than anyone from the Foundation)
User avatar
Posts: 3091
Joined: Sun Apr 22, 2012 4:50 pm
Location: Cambridge, UK
by DemonJim » Thu Jun 28, 2012 1:49 pm
AndrewS wrote:Isn't this pretty much what you're asking for / suggesting
http://elinux.org/R-Pi_Hub#Projects.2C_ ... _Tutorials :?:

(I believe the wiki is primarily updated by the community, rather than anyone from the Foundation)


Sorry I think you have misunderstood what I mean (unless I'm missing something on that page). My suggestion in the first post was to have an official guide for people who want to make their own guides. A guide for making guides. Teaching the teachers.

The idea is to try and give more consistency for total newbies who come across various community-driven tutorials and walkthroughs. I think it is important to consider this when people are making their own guides because the RasPi (and more importantly the software it comes with) will evolve over time, and many of these community guides created now will become out-dated and even irrelevant. Then, a total newbie will be faced with a plethora of misleading information about their new RasPi on the internet. Hope that explains what I mean a little better.
DemonStudios Ltd | Indie Game Developer | www.demonstudios.com
User avatar
Posts: 20
Joined: Thu Sep 01, 2011 2:19 pm
Location: UK
by AndrewS » Thu Jun 28, 2012 1:53 pm
Sorry for causing any confusion - my post was in response to:
"Here is a suggestion from the makers of my Excito B3 ARM NAS where they have produced a Wiki which nicely suggests small projects or tasks aimed at the beginner, intermediate or advanced user -

http://wiki.excito.org/wiki/index.php/T ... nd_How-tos

It would be great for the foundation to host a similar 'certified' information source rather than rely on us having to search HOW-TO's via Google."

...but I now see that cashaw was asking for "Foundation-written" guides, rather than "community-written" guides. :|
User avatar
Posts: 3091
Joined: Sun Apr 22, 2012 4:50 pm
Location: Cambridge, UK
by DemonJim » Thu Jun 28, 2012 2:34 pm
Aah yes sorry Andrew, it does appear that it was cashaw that totally missed the point I was making and took it off topic.

So cashaw all I was suggesting was that a single page on the Wiki lists a few guidelines for people who go ahead and create their own YouTube tutorials etc., not that the foundation should employ people to create a bunch of official tutorials. My reply saying about the Foundation employing more people by increasing the Model B price was purely to help streamline and really focus all the community efforts, not replace them.
DemonStudios Ltd | Indie Game Developer | www.demonstudios.com
User avatar
Posts: 20
Joined: Thu Sep 01, 2011 2:19 pm
Location: UK
by ghans » Thu Jun 28, 2012 2:36 pm
We'll the Official User Guide is finished and will be published this autumn via Amazon at John Wiley & Sons.

ghans
• Don't like the board ? Missing features ? Change to the prosilver theme ! You can find it in your settings.
• Don't like to search the forum BEFORE posting 'cos it's useless ? Try googling : yoursearchtermshere site:raspberrypi.org
Posts: 4407
Joined: Mon Dec 12, 2011 8:30 pm
Location: Germany
by abishur » Thu Jun 28, 2012 3:15 pm
DemonJim wrote: My suggestion in the first post was to have an official guide for people who want to make their own guides. A guide for making guides. Teaching the teachers.


So you want a bunch of open source die hards, to commit to a single format? :shock: :P

I don't disagree that in a perfect universe such a thing would exist and be strictly followed, but this is a community driven project and we have *zero* control over what the community puts out. We can't even get people to follow the guidelines for troubleshooting help on this very forum!
Dear forum: Play nice ;-)
User avatar
Forum Moderator
Forum Moderator
Posts: 4269
Joined: Thu Jul 28, 2011 4:10 am
Location: USA
by cashaw » Thu Jun 28, 2012 3:52 pm
DemonJim wrote:Aah yes sorry Andrew, it does appear that it was cashaw that totally missed the point I was making and took it off topic.

So cashaw all I was suggesting was that a single page on the Wiki lists a few guidelines for people who go ahead and create their own YouTube tutorials etc., not that the foundation should employ people to create a bunch of official tutorials. My reply saying about the Foundation employing more people by increasing the Model B price was purely to help streamline and really focus all the community efforts, not replace them.


No, I never suggested that the Foundation employs people to write official Wiki's and the like, but to have a link to a single consistent source of useful information, which can be community managed but to a foundation format giving a consistent source. My example of the webpage above which is hosted and managed by the small company making the product, but all submissions are made by the community. Just a sort of moderated wiki, not a full time job.

It was really just a way to have to stop having to Google for Raspberry Pi tutorials from different sources which may or may not be out of date, correct etc. Nothing stopping others writing their own things of course, but some place we could know that information is current and (semi) official.

(and I did wander off topic a bit by wondering if the foundation had plans to create suggested curriculums for school courses etc when the Pi does finally reach schools, i.e. is the foundation also supplying the educational eco-system or just funding for cheaper hardware for schools)
Posts: 71
Joined: Tue Mar 06, 2012 8:32 pm
by DemonJim » Thu Jun 28, 2012 3:58 pm
But as AndrewS pointed out that is exactly what the www.elinux.org/RaspberryPiBoard Wiki is (it is linked via the Wiki tab at the top right on the official http://www.raspberrypi.org website).

Admittedly it'd be better if it was one-click to the Wiki as opposed to clicking on a link from that page (which is only obvious when you know it's there).

Maybe it could be made into a really big button rather than just a text hyperlink?
Last edited by DemonJim on Thu Jun 28, 2012 4:05 pm, edited 1 time in total.
DemonStudios Ltd | Indie Game Developer | www.demonstudios.com
User avatar
Posts: 20
Joined: Thu Sep 01, 2011 2:19 pm
Location: UK
by DemonJim » Thu Jun 28, 2012 4:03 pm
abishur wrote:So you want a bunch of open source die hards, to commit to a single format? :shock: :P

I don't disagree that in a perfect universe such a thing would exist and be strictly followed, but this is a community driven project and we have *zero* control over what the community puts out. We can't even get people to follow the guidelines for troubleshooting help on this very forum!


I think I am indeed living in Fantasyland, USA. Population: me :D

I suppose if the RasPi doesn't actually ever really change very much then outdated information is not quite so much of a concern anyway. Apart from getting a case and going through some inevitable PCB revisions to make it smaller/cheaper etc. then there's no real issue on that score as these changes are really obvious. It's changes to the built-in software that will be the main issue (e.g. if a later model decides to use a totally new default GUI, or a package is removed).
DemonStudios Ltd | Indie Game Developer | www.demonstudios.com
User avatar
Posts: 20
Joined: Thu Sep 01, 2011 2:19 pm
Location: UK
by cashaw » Thu Jun 28, 2012 9:03 pm
DemonJim wrote:But as AndrewS pointed out that is exactly what the http://www.elinux.org/RaspberryPiBoard Wiki is (it is linked via the Wiki tab at the top right on the official http://www.raspberrypi.org website).

Admittedly it'd be better if it was one-click to the Wiki as opposed to clicking on a link from that page (which is only obvious when you know it's there).

Maybe it could be made into a really big button rather than just a text hyperlink?


Opps, cap firmly in hand. All I had seen to the elinux forum was the "peripherals" page and had missed all the tutorial pages. Sorry !

It would be good to highlight the wiki on the front page, there are some good 'getting started' projects on there which could help the beginners..
Posts: 71
Joined: Tue Mar 06, 2012 8:32 pm