Re: better documentation!
Re: better documentation!
Please read my postings at the following URL, along with those of other Puppians. Thanks!
http://www.murga-linux.com/puppy/viewtopic.php?t=32183
http://www.murga-linux.com/puppy/viewtopic.php?t=32183
John Hechtman / www.zenarrow.com / jhecht@ix.netcom.com
"Computer help in NYC" / 917 628 0192 - cell / 212 586 4633 - landline
"Computer help in NYC" / 917 628 0192 - cell / 212 586 4633 - landline
Hi John,
do you know this one?
http://www.puppylinux.org/manual
The problem that I see with printed books, is, that they are quickly out of date.
We think of bundling a printed booklet based on Olis handbook for Muppy, in case we have success in finding a partner to sell computers with Muppy pre-installed.
Of course we have contact with Oli concerning these plans.
This however is different as a standalone book, as it is valid only for the system, it is sold with.
But I am curious to see the results of this poll
Mark
do you know this one?
http://www.puppylinux.org/manual
The problem that I see with printed books, is, that they are quickly out of date.
We think of bundling a printed booklet based on Olis handbook for Muppy, in case we have success in finding a partner to sell computers with Muppy pre-installed.
Of course we have contact with Oli concerning these plans.
This however is different as a standalone book, as it is valid only for the system, it is sold with.
But I am curious to see the results of this poll
Mark
[url=http://murga-linux.com/puppy/viewtopic.php?p=173456#173456]my recommended links[/url]
Mark wrote:
>Hi John,
>do you know this one?
>http://www.puppylinux.org/manual
>
>The problem that I see with printed books, is, that they are quickly out >of date.
>
>We think of bundling a printed booklet based on Olis handbook for >Muppy, in case we have success in finding a partner to sell computers >with Muppy pre-installed.
>Of course we have contact with Oli concerning these plans.
>This however is different as a standalone book, as it is valid only for the >system, it is sold with.
>
>But I am curious to see the results of this poll (Smile)
>
>Mark
Your point about being quickly obsolete is valid - but could be overcome with a POD setup (Print On Demand). As new revisions are made, the POD master is updated, so the reader can always get the latest/greatest.
Also, in installing Puppy to older computers, very little would change, as it is likely one would use an older version of Puppy, for compatibility with the older hardware.
I was aware of the v3 manual, and am delighted to see the v4. But I have objections to how it is written, that in no way are meant to denigrate the good work that has gone into it.
Given that the manual is Web-based, there should be MUCH better links to information in it. I will quote a short section of it, and insert the comments I want to make in the original text. Where I want to change something <I will put my comment in carets> so it will be easy to distinguish what I write from the original text.
From the Puppy v4 manual:
How to run Puppy the very first time
First you must set up the boot sequence in the BIOS. If you do not know how to get into the BIOS-setup, consult the computers manual. <or Google for the make/model computer you have - most people don't have the manual> Usually you press one of the following keys immediately after switching on the PC: ESC, one of the function keys F1 to F12 or the delete key. <there are lists on the Web of the correct key sequence for almost every computer maker in the world - a link should go here> At the BIOS-setup you change the boot sequence so that the CD-ROM drive is first and the harddrive is second. Close the BIOS-setup and store the settings.
The v4 manual is not bad - but still presupposes a level of knowledge that may/may not exist in the person reading it. So the manual glosses over key steps, assuming that the EU (end user) knows how to do an operation.
Another example is that the EU is told to consult his CD burning software manual about how to burn iso files. But not all CD burning software permits this - and again the manual may not exist. Instead, a link should be placed, pointing to CDBurnerXP <http://cdburnerxp.se/> or one of the other freeware software packages available.
It's very hard to spell out every step in documentation - but it's the key to having docs that will work for the greenest newbie, as well as the veteran 'nix head...
Other comments?
More screen shots are needed
Screen shots for the English manual should be in English (grin)
>Hi John,
>do you know this one?
>http://www.puppylinux.org/manual
>
>The problem that I see with printed books, is, that they are quickly out >of date.
>
>We think of bundling a printed booklet based on Olis handbook for >Muppy, in case we have success in finding a partner to sell computers >with Muppy pre-installed.
>Of course we have contact with Oli concerning these plans.
>This however is different as a standalone book, as it is valid only for the >system, it is sold with.
>
>But I am curious to see the results of this poll (Smile)
>
>Mark
Your point about being quickly obsolete is valid - but could be overcome with a POD setup (Print On Demand). As new revisions are made, the POD master is updated, so the reader can always get the latest/greatest.
Also, in installing Puppy to older computers, very little would change, as it is likely one would use an older version of Puppy, for compatibility with the older hardware.
I was aware of the v3 manual, and am delighted to see the v4. But I have objections to how it is written, that in no way are meant to denigrate the good work that has gone into it.
Given that the manual is Web-based, there should be MUCH better links to information in it. I will quote a short section of it, and insert the comments I want to make in the original text. Where I want to change something <I will put my comment in carets> so it will be easy to distinguish what I write from the original text.
From the Puppy v4 manual:
How to run Puppy the very first time
First you must set up the boot sequence in the BIOS. If you do not know how to get into the BIOS-setup, consult the computers manual. <or Google for the make/model computer you have - most people don't have the manual> Usually you press one of the following keys immediately after switching on the PC: ESC, one of the function keys F1 to F12 or the delete key. <there are lists on the Web of the correct key sequence for almost every computer maker in the world - a link should go here> At the BIOS-setup you change the boot sequence so that the CD-ROM drive is first and the harddrive is second. Close the BIOS-setup and store the settings.
The v4 manual is not bad - but still presupposes a level of knowledge that may/may not exist in the person reading it. So the manual glosses over key steps, assuming that the EU (end user) knows how to do an operation.
Another example is that the EU is told to consult his CD burning software manual about how to burn iso files. But not all CD burning software permits this - and again the manual may not exist. Instead, a link should be placed, pointing to CDBurnerXP <http://cdburnerxp.se/> or one of the other freeware software packages available.
It's very hard to spell out every step in documentation - but it's the key to having docs that will work for the greenest newbie, as well as the veteran 'nix head...
Other comments?
More screen shots are needed
Screen shots for the English manual should be in English (grin)
John Hechtman / www.zenarrow.com / jhecht@ix.netcom.com
"Computer help in NYC" / 917 628 0192 - cell / 212 586 4633 - landline
"Computer help in NYC" / 917 628 0192 - cell / 212 586 4633 - landline
Oli, who generously devoted so much time to creating the English manual, does not have English as a first language. That makes his achievement so much the greater IMHO.jhecht wrote:The v4 manual is not bad - but still presupposes a level of knowledge that may/may not exist in the person reading it. So the manual glosses over key steps, assuming that the EU (end user) knows how to do an operation....
Other comments?
More screen shots are needed
Screen shots for the English manual should be in English (grin)
He has recently asked for someone to take over editing the English manual, because he needs to concentrate on the German version, which is his native language.
I believe Oli got at least one taker to update the English manual but, given your ideas and background, it would be great if you also took up the challenge. Simply PM HairyWill and he will grant you editing permission on the manual in the wiki.
That should be the starting point for getting your ideas into concrete practice and has the added benefit that Oli and the other non-English translators can transfer your changes to their versions, too.
Cheers
[i]Actions speak louder than words ... and they usually work when words don't![/i]
SIP:whodo@proxy01.sipphone.com; whodo@realsip.com
SIP:whodo@proxy01.sipphone.com; whodo@realsip.com
WhoDo said:
WD>I believe Oli got at least one taker to update the English manual but, given your ideas and background, it would be great if you also took up the challenge. Simply PM HairyWill and he will grant you editing permission on the manual in the wiki.
WD>That should be the starting point for getting your ideas into concrete practice and has the added benefit that Oli and the other non-English translators can transfer your changes to their versions, too.
I would be happy (and honored) to >help< fine tune the English version of the manual as time permits. I can't assume total responsibility for it, but will contribute when I can. Thank you for the suggestion!
WD>I believe Oli got at least one taker to update the English manual but, given your ideas and background, it would be great if you also took up the challenge. Simply PM HairyWill and he will grant you editing permission on the manual in the wiki.
WD>That should be the starting point for getting your ideas into concrete practice and has the added benefit that Oli and the other non-English translators can transfer your changes to their versions, too.
I would be happy (and honored) to >help< fine tune the English version of the manual as time permits. I can't assume total responsibility for it, but will contribute when I can. Thank you for the suggestion!
John Hechtman / www.zenarrow.com / jhecht@ix.netcom.com
"Computer help in NYC" / 917 628 0192 - cell / 212 586 4633 - landline
"Computer help in NYC" / 917 628 0192 - cell / 212 586 4633 - landline
- Lobster
- Official Crustacean
- Posts: 15522
- Joined: Wed 04 May 2005, 06:06
- Location: Paradox Realm
- Contact:
I would be happy (and honored) to >help<
Well done
I created some of the early manuals here
http://tmxxine.com/wik/wikka.php?wakka=PuppyLove
- a great way to learn
My recommendation would be a ring binder type manual
with updates with dates for pages
A Puppy sized manual would be great
. . . and why not a Puppy manual ISO or SFS?
Last edited by Lobster on Sat 27 Sep 2008, 15:06, edited 1 time in total.
No thank you for the offer of help. I'm sure it will be appreciated by the present manual maintainers, especially those working on the English version.jhecht wrote:I would be happy (and honored) to >help< fine tune the English version of the manual as time permits. I can't assume total responsibility for it, but will contribute when I can. Thank you for the suggestion!
I note elsewhere that you were concerned about wiki editing. Lobster's link is a good place to start. There is also a manual sandbox on puppylinux.org that lets you make changes without affecting the copy on display. I promise you will wonder what you were worried about when you've had a chance to play around in the sandbox a bit.
Any time you can devote to implementing your excellent ideas will be greatly appreciated. Thank you again.
[i]Actions speak louder than words ... and they usually work when words don't![/i]
SIP:whodo@proxy01.sipphone.com; whodo@realsip.com
SIP:whodo@proxy01.sipphone.com; whodo@realsip.com
- battleshooter
- Posts: 1378
- Joined: Wed 14 May 2008, 05:10
- Location: Australia
I think a book is a pretty cool idea. But MU does have a point. Considering how quick Puppy moves, any book would be out of date very soon. Maybe an online book (documentation) is the key. As a note, I'm not sick of looking through the forums and Google for what I need, I just think a book would be a cool idea., but there was no other options
- ttuuxxx
- Posts: 11171
- Joined: Sat 05 May 2007, 10:00
- Location: Ontario Canada,Sydney Australia
- Contact:
Things like grub, or xorgwizard or even dialup haven't changed all that much visually over the years on puppy, Internally they have, but not what the user actually sees.
Tell ya the truth I would rather see some divx or vcd how-to clips.
Some people just hate reading and like to watch videos.
ttuuxxx
Tell ya the truth I would rather see some divx or vcd how-to clips.
Some people just hate reading and like to watch videos.
ttuuxxx
http://audio.online-convert.com/ <-- excellent site
http://samples.mplayerhq.hu/A-codecs/ <-- Codec Test Files
http://html5games.com/ <-- excellent HTML5 games :)
http://samples.mplayerhq.hu/A-codecs/ <-- Codec Test Files
http://html5games.com/ <-- excellent HTML5 games :)
A real world example of a well written bookIt's very hard to spell out every step in documentation - but it's the key to having docs that will work for the greenest newbie, as well as the veteran 'nix head...
Other comments?
http://www.slackbook.org/
to help you along with ideas
big_bass
- darrelljon
- Posts: 551
- Joined: Sun 08 Apr 2007, 11:10
- Contact:
I just created a print on demand book at cafepress. It is a beginners manual for Puppy Linux 1 - 4. I am interested in helping with documentation in general.
Documentation
Fine business Darrell on your book but I had hoped to see a bit of the layout/format of said publication.
I am living proof that what big_bass said is spot on and here is a scope of a simple procedure that big_bass clarified for me a while back although not exactly the same format but basically same information.
Scope: Converting a ?.tgz file to a ?.pet file
1.download ?.tgz that is of interest to the user
2.Go to dorectory where ?.tgz was saved
3.Right click on vacant area in folder
4.click on "window tab"
5.then click on "terminal tab" and "Xterm" will open
6.then type in "tgz2pet ?.tgz
7. then press enter
8.when the ?.pet file is complete,then simply click on ?.pet to install
I realize of course this is basic,basic but if a newbie is not aware of this procedure he will be looking like our little friend here " "
Thanks big_bass
I am living proof that what big_bass said is spot on and here is a scope of a simple procedure that big_bass clarified for me a while back although not exactly the same format but basically same information.
Scope: Converting a ?.tgz file to a ?.pet file
1.download ?.tgz that is of interest to the user
2.Go to dorectory where ?.tgz was saved
3.Right click on vacant area in folder
4.click on "window tab"
5.then click on "terminal tab" and "Xterm" will open
6.then type in "tgz2pet ?.tgz
7. then press enter
8.when the ?.pet file is complete,then simply click on ?.pet to install
I realize of course this is basic,basic but if a newbie is not aware of this procedure he will be looking like our little friend here " "
Thanks big_bass
I don't know that I would buy a book, but I would love to be able to borrow one from a library, or to download a copy. As a complete newbie I find the manual to have a lot of holes in it, with some things that don't seems to make sense, and some things that aren't there (like what to do with sfs files).
Something as simple as Bill suggests is what people like me need or we'll just go back to windows because we can normally find a friend to sit with us ad show us how things work with that.
Something as simple as Bill suggests is what people like me need or we'll just go back to windows because we can normally find a friend to sit with us ad show us how things work with that.
Documentation
Hi Bones01,I understand exactly what you are saying about manuals having "holes" in the documentation which makes them cryptic and pretty
difficult for a green newbie to understand.I reckon it takes one newbie to another to undertand this because most of the experienced users already know these procedures but how they learned them is still a mystery to me,maybe years and years of study.? In so far as NOT buying a manual with "step by step" procedures enclosed,I for one wouldn't hesitate to purchase them because a new user could hit the ground running in Puppy Linux ,almost immediately. Yes,there are many more things anyone would have to learn but the foundation would be quick and painless.Questions !? Yes ! I have many of them ,but until these are made known to me,I will just putter along and do the best I can.
Lastly on your idea that folks might get discouraged and go back to BrandX software,I am sure this happens but just for instance,a week ago my hard drive went walkabout but after removing it,I was still able to surf the net,send/receive emails etc.all using Puppy 4 Dingo and this absolutely amazed me because I know of no other way I could have done that,except a "liveCD" or maybe a memory stick.All is well in "Puppy Land" cheers.bill
difficult for a green newbie to understand.I reckon it takes one newbie to another to undertand this because most of the experienced users already know these procedures but how they learned them is still a mystery to me,maybe years and years of study.? In so far as NOT buying a manual with "step by step" procedures enclosed,I for one wouldn't hesitate to purchase them because a new user could hit the ground running in Puppy Linux ,almost immediately. Yes,there are many more things anyone would have to learn but the foundation would be quick and painless.Questions !? Yes ! I have many of them ,but until these are made known to me,I will just putter along and do the best I can.
Lastly on your idea that folks might get discouraged and go back to BrandX software,I am sure this happens but just for instance,a week ago my hard drive went walkabout but after removing it,I was still able to surf the net,send/receive emails etc.all using Puppy 4 Dingo and this absolutely amazed me because I know of no other way I could have done that,except a "liveCD" or maybe a memory stick.All is well in "Puppy Land" cheers.bill
I like the Manual, but would like to print it so I could refer to a printed page when going through a procedure (specifically my first full install).
When I try to print a page with step-by-step images, my printer stops after the first image.
Is there a simple way that I am missing of printing?
Steve
When I try to print a page with step-by-step images, my printer stops after the first image.
Is there a simple way that I am missing of printing?
Steve
Hello,
As a contributer to the the Puppy 4 manual, the question of written information becoming obsolete was a major problem for me, as Puppy changes, sometimes drastically, between releases..
I believe a Wiki is a good answer...
As a contributer to the the Puppy 4 manual, the question of written information becoming obsolete was a major problem for me, as Puppy changes, sometimes drastically, between releases..
I believe a Wiki is a good answer...
Close the Windows, and open your eyes, to a whole new world
I am Lead Dog of the
Puppy Linux Users Group on Facebook
Join us!
Puppy since 2.15CE...
I am Lead Dog of the
Puppy Linux Users Group on Facebook
Join us!
Puppy since 2.15CE...
Help needed for the English manual (4.21 - 4.31)
Hi all. Allow me to bump this thread up.
After the attack on the site, the images of the English manual were lost. (prit1 has a copy, but maybe that will not be needed anymore*.)
If you can recreate the missing images (no wider than 500 px) and post here, then that will be a lot of help. These are the pages that need the images (Feel free to post the corrected article [if any] and the images here). Thanks!
Manual-English01.txt
Manual-English02.txt
Manual-English04.txt
Manual-English05.txt
Manual-English06.txt
Manual-English08.txt
Manual-English09.txt
* We are no longer retrieving the old images as they were based on a Puppy earlier than 4.21, and we want documentation for both 4.21 and 4.31 (if there is a difference, that is). Also, many of the screenshots were German (but thanks to oli for working on the English manual ).
ALSO, if you want to work on other languages and know how to handle a database dump, PM me and I will give you the Drupal database dump.
Thanks!
After the attack on the site, the images of the English manual were lost. (prit1 has a copy, but maybe that will not be needed anymore*.)
If you can recreate the missing images (no wider than 500 px) and post here, then that will be a lot of help. These are the pages that need the images (Feel free to post the corrected article [if any] and the images here). Thanks!
Manual-English01.txt
Manual-English02.txt
Manual-English04.txt
Manual-English05.txt
Manual-English06.txt
Manual-English08.txt
Manual-English09.txt
* We are no longer retrieving the old images as they were based on a Puppy earlier than 4.21, and we want documentation for both 4.21 and 4.31 (if there is a difference, that is). Also, many of the screenshots were German (but thanks to oli for working on the English manual ).
ALSO, if you want to work on other languages and know how to handle a database dump, PM me and I will give you the Drupal database dump.
Thanks!
Puppy user since Oct 2004. Want FreeOffice? [url=http://puppylinux.info/topic/freeoffice-2012-sfs]Get the sfs (English only)[/url].
TY
Gee, thanks for the help. FYI, I've had only virtual sleep since Monday of the site attack (3 nights ago), as matters like those can't de postponed. But so is my Friday work deadline.
Puppy user since Oct 2004. Want FreeOffice? [url=http://puppylinux.info/topic/freeoffice-2012-sfs]Get the sfs (English only)[/url].