Re: better documentation!

Helping keep Puppy well documented
Post Reply

If a really good book was written about using Puppy, would you buy it?

Yes - I'm tired of searching the forums!
12
67%
No - the forums and Google are all I need!
6
33%
 
Total votes: 18

Message
Author
User avatar
jhecht
Posts: 227
Joined: Sun 29 Jan 2006, 17:36
Location: New York City (Manhattan)
Contact:

Re: better documentation!

#1 Post by jhecht »

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
John Hechtman / www.zenarrow.com / jhecht@ix.netcom.com
"Computer help in NYC" / 917 628 0192 - cell / 212 586 4633 - landline

User avatar
MU
Posts: 13649
Joined: Wed 24 Aug 2005, 16:52
Location: Karlsruhe, Germany
Contact:

#2 Post by MU »

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
[url=http://murga-linux.com/puppy/viewtopic.php?p=173456#173456]my recommended links[/url]

User avatar
jhecht
Posts: 227
Joined: Sun 29 Jan 2006, 17:36
Location: New York City (Manhattan)
Contact:

#3 Post by jhecht »

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)
John Hechtman / www.zenarrow.com / jhecht@ix.netcom.com
"Computer help in NYC" / 917 628 0192 - cell / 212 586 4633 - landline

User avatar
WhoDo
Posts: 4428
Joined: Wed 12 Jul 2006, 01:58
Location: Lake Macquarie NSW Australia

#4 Post by WhoDo »

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

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

User avatar
jhecht
Posts: 227
Joined: Sun 29 Jan 2006, 17:36
Location: New York City (Manhattan)
Contact:

#5 Post by jhecht »

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! :)
John Hechtman / www.zenarrow.com / jhecht@ix.netcom.com
"Computer help in NYC" / 917 628 0192 - cell / 212 586 4633 - landline

User avatar
Lobster
Official Crustacean
Posts: 15522
Joined: Wed 04 May 2005, 06:06
Location: Paradox Realm
Contact:

#6 Post by Lobster »

I would be happy (and honored) to >help<
Image

Well done
I created some of the early manuals here
http://tmxxine.com/wik/wikka.php?wakka=PuppyLove

- a great way to learn :D

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.
Puppy Raspup 8.2Final 8)
Puppy Links Page http://www.smokey01.com/bruceb/puppy.html :D

User avatar
WhoDo
Posts: 4428
Joined: Wed 12 Jul 2006, 01:58
Location: Lake Macquarie NSW Australia

#7 Post by WhoDo »

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

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

User avatar
battleshooter
Posts: 1378
Joined: Wed 14 May 2008, 05:10
Location: Australia

#8 Post by battleshooter »

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

User avatar
ttuuxxx
Posts: 11171
Joined: Sat 05 May 2007, 10:00
Location: Ontario Canada,Sydney Australia
Contact:

#9 Post by ttuuxxx »

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
http://audio.online-convert.com/ <-- excellent site
http://samples.mplayerhq.hu/A-codecs/ <-- Codec Test Files
http://html5games.com/ <-- excellent HTML5 games :)

big_bass
Posts: 1740
Joined: Mon 13 Aug 2007, 12:21

#10 Post by big_bass »

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?
A real world example of a well written book
http://www.slackbook.org/

to help you along with ideas

big_bass

User avatar
darrelljon
Posts: 551
Joined: Sun 08 Apr 2007, 11:10
Contact:

#11 Post by darrelljon »

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.

bill
Posts: 490
Joined: Wed 28 May 2008, 15:32

Documentation

#12 Post by bill »

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 " :roll: "
Thanks big_bass

bones01
Posts: 371
Joined: Mon 11 Aug 2008, 07:47
Location: Melbourne, Aus

#13 Post by bones01 »

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.

bill
Posts: 490
Joined: Wed 28 May 2008, 15:32

Documentation

#14 Post by bill »

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. :D 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 :cry: 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

stevesr0
Posts: 169
Joined: Sun 24 Jun 2007, 17:25

#15 Post by stevesr0 »

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

User avatar
puppyluvr
Posts: 3470
Joined: Sun 06 Jan 2008, 23:14
Location: Chickasha Oklahoma
Contact:

#16 Post by puppyluvr »

:D 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...
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...

raffy
Posts: 4798
Joined: Wed 25 May 2005, 12:20
Location: Manila

Help needed for the English manual (4.21 - 4.31)

#17 Post by raffy »

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!
Puppy user since Oct 2004. Want FreeOffice? [url=http://puppylinux.info/topic/freeoffice-2012-sfs]Get the sfs (English only)[/url].

puppyite

#18 Post by puppyite »

Hi Raffy,
Time permitting I will make your screenshots.

raffy
Posts: 4798
Joined: Wed 25 May 2005, 12:20
Location: Manila

TY

#19 Post by raffy »

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. :roll:
Puppy user since Oct 2004. Want FreeOffice? [url=http://puppylinux.info/topic/freeoffice-2012-sfs]Get the sfs (English only)[/url].

Post Reply