community documentation - getting started guide

[Turbo-Frambozenbier]

Hi all,

Myself, Ozzy and Liam Fraser wanted to ask a few questions about community documentation.

We had a discussion on this forum a few weeks ago regarding the best way to produce it:

(quote)

I think the documentation being:

1) "born" on the wiki

2) peer reviewed on the wiki (and approved)

3) then translated by community members

4) then published as a full article or PDF

…is a good place to start, unless anyone has any more suggestions?

(end quote)

And this seemed to be the general concensus of the thread...

The first thing We're planning on creating is a "getting started" guide for the RasPi ,that takes a user from opening the box, connecting it up, installing an OS and tools, right up to creating the RasPi shooter game that Liam has been creating you tube tutorials on.(A bit like you got with a Commodore 64, just to get you started)

So before I go into any detail about the sections and content we think we need, and the people who have already signed up to help us we just need to ask the community a couple of questions:

1) Is anybody else already working on something like this that we shoudl team up with? (Eben and Liz just emailed us, and don't seem to think so)

2) Can we create some new pages under the eLinux wiki to host this (to the nice people at eLinux)?

3) Can we get volunteers to translate this for us into different languages from the wiki as it develops?

If this looks like the best way to go I'll post more information here about what we would like to create, whos already agreed to help us, and how you can get involved yourself, once we've got some feedback from the forum.

Best regards,

Turbo, Ozzy and Liam

[gimliflea]

there is already a getting started guide on the wiki, it is fairly basic but couldn't you just review and extend it as you think fit?

[Turbo-Frambozenbier]

gimliflea said:


there is already a getting started guide on the wiki, it is fairly basic but couldn't you just review and extend it as you think fit?



Yes, we were thinking of taking what was already there and extending it, but also thinking about getting more organised and putting up a skeleton of sections and categories so that people can help us fill in the gaps.

I/we personally like the community/wiki approach but sometimes it helps to map things out first to help people put things in the right place, and provide info at the right level of detail.

So if you start with categories or chapters and give people an idea of the kind of content we are looking for you end up with something that reads like a book and doesn't jump randomly between the basics of a HDMI connection and a picture or diagram of the connection, all mixed up with the engineering info, low level detail and pin-outs for the connection (just as an example).

A the moment we are thinking that we need:

1st - Getting Started guide (top priority).

2nd - Simple examples of how to interface and interact with the board from a programming perspective.

3rd - Simple examples of how to interface and interact with the board from a GertBoard, Arduino or electronics perspective.

4rd - Practical guide to installing, configuring and deploying RasPis in an educational  or training environment ahead of the new school year.

... and the rest should follow as more people get hold of them, as long as people are shown enough to get them started.

Between ourselves we have talked about a continuous theme of:

Build > Develop > Share

(repeat)

Where people can BUILD something and learn from others, DEVELOP the idea and improve it, then SHARE it with others as a new recipie or blue-print.

At this point we are just trying to make sure that we are going in the right direction and producing something that people actually want or need, without duplicating or wasting effort.

[johnbeetem]

My suggestion is to leave it at the Wiki level.  RasPi software will be continually evolving, as will suggestions for interface circuitry.  Doing it as a Wiki will also make it more adaptable to later RasPi versions and add-ons as they occur.

Is there a program to automatically convert the RasPi Wiki into a PDF for off-line use?

[Robert_M]

John Beetem said:


Is there a program to automatically convert the RasPi Wiki into a PDF for off-line use?


As a side note, this has been something I've wondered about for some time - not RaspPi, specifically, but just in general. I've come across wiki-like sites in the past and wished I had a PDF version to take offline.

[Turbo-Frambozenbier]

Robert_M said:


John Beetem said:


Is there a program to automatically convert the RasPi Wiki into a PDF for off-line use?


As a side note, this has been something I've wondered about for some time - not RaspPi, specifically, but just in general. I've come across wiki-like sites in the past and wished I had a PDF version to take offline.



we have one, he is called Ozzy (graphic designer by day, webmaster by night)

but on a more serious note:

http://www.mediawiki.org/wiki/.....Pdf_Export

[grumpyoldgit]

On the Wikipedia site itself there is a print/export option on the left had side of the page.

[Turbo-Frambozenbier]

Turbo-Frambozenbier said:


Robert_M said:


John Beetem said:


Is there a program to automatically convert the RasPi Wiki into a PDF for off-line use?


As a side note, this has been something I've wondered about for some time - not RaspPi, specifically, but just in general. I've come across wiki-like sites in the past and wished I had a PDF version to take offline.


we have one, he is called Ozzy (graphic designer by day, webmaster by night)

but on a more serious note:

http://www.mediawiki.org/wiki/.....Pdf_Export



Replying to my own post:

This one too:

http://www.mediawiki.org/wiki/.....n:Pdf_Book

however it looks like both tools need to be installed by the site owner on the server, not the visitor on their computer.

[kasperl]

I don't think I'm the right person to write beginners manuals, but I'd be willing to have a quick go at a Dutch translation (my native language), as long as  it's a one-time job and an acceptable amount of pages. Fully maintaining a translation is not something I can commit to, but if you guys push major sets of changes out at reasonably long intervals, it wouldn't be hard to keep things within the same half year or so. Doing basic Dutch support would be OK as well.

[Lynbarn]

Robert_M said:


John Beetem said:


Is there a program to automatically convert the RasPi Wiki into a PDF for off-line use?




For Windows, there are a number of PDF-generators that install as printer drivers - simply print the page using the pseudo-printer and, when prompted, give the file a name. The one I use is Cute-PDF. Similar facilities are available for Linux, such as THIS.

[liamfraser280]

Hi all,

Just thought I'd show my face here as I've only just noticed the topic has been made .

I doubt the getting started guide will change much so won't need constant updating. The stuff that does need updating a lot on the wiki should probably stay there.

Ozzy's pdf's are really good. Think revision guide kind of layout. If you were printing it out it would be far better in terms of layout than simply printing the wikipedia pages.

It wouldn't just be guides: cheat sheats and other useful resources. It might even be an idea to use the 'Professor Pi' character as shown in this thread here. http://www.raspberrypi.org/for.....-character

I think it looks great .

Cheers all,

Liam.

[Robert_M]

Thanks for the PDF generator links

[Bengaul]

Liam Fraser said:



Ozzy's pdf's are really good. Think revision guide kind of layout. If you were printing it out it would be far better in terms of layout than simply printing the wikipedia pages.


I preferred his work with Black Sabbath myself.

[JeToMad]

Turbo-Frambozenbier said:


3) Can we get volunteers to translate this for us into different languages from the wiki as it develops?



I could help with Spanish translation. What I can't assure you is how fast I will be able to translate it, since depends on the free time I get from work, family and so...

[Turbo-Frambozenbier]

Bengaul said:


Liam Fraser said:



Ozzy's pdf's are really good. Think revision guide kind of layout. If you were printing it out it would be far better in terms of layout than simply printing the wikipedia pages.


I preferred his work with Black Sabbath myself.



ozzy is ok.

"We were getting paranoid that he was going off the rails like a crazy train, but he was just going through changes and barking at the moon".

I think we should probably start with something simple like a 2 page flyer for the device (what it is and why the foundation needed to build it).

Once we have this we can have an OzzFest with the translations as a dummy-run for a future guides.

[JeToMad]

Hey Turbo, about the translations... Will you wait to have the final version, or can be advanced with the drafts you have at the moment?

And about your web (I looked a bit there...), am I doing something wrong, or the language select feature does not work? I tried spanish, catalonian, and some others, and it seems to trigger google translate, but the text is still in english even when google shows an option to switch back to the original language :O

By the way, I am using chrome (I don't know if it may be browser related, but seems unlikely being the google browser and a google feature...)

[Turbo-Frambozenbier]

JeToMad said:


Hey Turbo, about the translations... Will you wait to have the final version, or can be advanced with the drafts you have at the moment?

And about your web (I looked a bit there...), am I doing something wrong, or the language select feature does not work? I tried spanish, catalonian, and some others, and it seems to trigger google translate, but the text is still in english even when google shows an option to switch back to the original language :O

By the way, I am using chrome (I don't know if it may be browser related, but seems unlikely being the google browser and a google feature...)



Hi JeToMad,

We are creating some new content for the launch, so it will be new content.

We are starting this tonight on the eLinux Wiki (anybody from eLinux here that could get in contact with us before we start please?)

It can be community editied/reviewed until we are happy with it, and at that point we will need translations. The first will be a simple 2 page flyer just to get us started.

(I've just tried the translation on the frambozenbier.org site again and it works ok for me on 4 different browsers, including chrome on 2 different computers, but I'll have another look later today)

Thanks for your help with the translations.

[JeToMad]

Weird thing: Today it works (Should have tried before posting, but assumed it will be like yesterday).

I don't like automatic translation (I don't like neither some human translations, and yesterday had a friend complaining about a book I really enjoyed... because of the spanish translation. Happily I readed the book in english... but that's offtopic... ) but wanted to try the feature. As said, now it works. Maybe it had something to do with cookies, or somenting like that.

Anyways, what I wanted to say is that the web looks great! Now it is time to fullfill it with content I mean from more people: that's the point on open projects.

[dognosh]

gimliflea said:


there is already a getting started guide on the wiki, it is fairly basic but couldn't you just review and extend it as you think fit?


I do like the idea of having everything related to a certain topic in one file , like "Getting started Basics" or "Advanced RPi" , also more peeps reviewing the whole of each section might fix vaguenesses like which "Transcend SDHC 8GB class 6" exactly can we use on the RPi ? as there are more than one model on sale right now

[Turbo-Frambozenbier]

JeToMad said:


Weird thing: Today it works (Should have tried before posting, but assumed it will be like yesterday).

I don't like automatic translation (I don't like neither some human translations, and yesterday had a friend complaining about a book I really enjoyed... because of the spanish translation. Happily I readed the book in english... but that's offtopic... ) but wanted to try the feature. As said, now it works. Maybe it had something to do with cookies, or somenting like that.

Anyways, what I wanted to say is that the web looks great! Now it is time to fullfill it with content I mean from more people: that's the point on open projects.



Agree. Automatic translation is terrible, but for now it is all we have.

And yes, it's anoying that we dont have more content on the site yet, but until the devices start shipping there is not much we can do as far as practical examples.

We have also been busy on a few side projects, but are now back on the site full time.

[Jaseman]

I'm thinking about writing my own manual without any collaboration.  I don't want to be bogged down with arguments about the content and trying to cater for every possible configuration.  My manual would be aimed at the sort of person that will buy the standard preloaded Fedora SD-card, doesn't want to get into 'how to set up linux on an SD card'.  They will get straight into using what has been provided, at a very slow step-by-step pace and with as little techno-babble as possible.  I think there is a demographic audience that will appreciate this.  I'm not too interested in helping the ones that already have the confidence to do their own research.

[jamesh]

I think that writing a manual by collaboration would be a long winded and fairly unpleasant experience! No problems with proof reading after the event, and giving advice and editorial at that stage.

[Miskatonic]

I've already began translating the wiki's homepage in French, considering it's my native language

I'm very willing to translate more content to French, just tell us when we can start the hard work !

[Turbo-Frambozenbier]

Jaseman said:


I'm thinking about writing my own manual without any collaboration.  I don't want to be bogged down with arguments about the content and trying to cater for every possible configuration.  My manual would be aimed at the sort of person that will buy the standard preloaded Fedora SD-card, doesn't want to get into 'how to set up linux on an SD card'.  They will get straight into using what has been provided, at a very slow step-by-step pace and with as little techno-babble as possible.  I think there is a demographic audience that will appreciate this.  I'm not too interested in helping the ones that already have the confidence to do their own research.



Hi Jaseman,

That is the kind of documentation we are starting with. A simple "dummies" guide to solve a specific task, not an epic novel like "war and peace".

We have accidentally stumbled upon a 2-page double-sided UK A4 (or US Letter) size datasheet, that seems to work well and provide just enough information to be useable without being overwhelming.

I am due to start putting the first four of our 2-page guides up on the eLinux wiki today for review and translation. We planned on doing this yesterday but we were juggling this with helping Liam with the torrents last night (didn't he do well).

We already have a the first few 2-page guides almost complete as "print ready" PDF's, but Liz reviewed them this morning and pointed out a couple of minor corrections and issues with a photo and image we used (where the copyright belongs to a third party and not the foundation), so these just need fixing first before we can show anyone them.

Jaseman: If you drop me a line on email and pass on your details we can take your content and format it in the same style as the other guides (without trying to modify your content, or have a public discussion about what should or shouldn't be in it).

The same goes for anyone else who thinks they could contribute two pages of text on a particular topic, or translate a topic, but couldn't write a whole document from start to finish.

If you email me at turbo@fram...org I can do the necessary work to get it translated and turned into a PDF guide.

Best regards,

Turbo