Puppy Linux Discussion Forum Forum Index Puppy Linux Discussion Forum
Puppy HOME page : puppylinux.com
"THE" alternative forum : puppylinux.info
 
 FAQFAQ   SearchSearch   MemberlistMemberlist   UsergroupsUsergroups   RegisterRegister 
 ProfileProfile   Log in to check your private messagesLog in to check your private messages   Log inLog in 

The time now is Thu 27 Nov 2014, 00:44
All times are UTC - 4
 Forum index » Advanced Topics » Puppy Projects » Documentation Project
Re: better documentation!
Moderators: Flash, JohnMurga, puppian
Post_new_topic   Reply_to_topic View_previous_topic :: View_next_topic
Page 1 of 2 Posts_count   Goto page: 1, 2 Next

If a really good book was written about using Puppy, would you buy it?
Yes - I'm tired of searching the forums!
64%
 64%  [ 11 ]
No - the forums and Google are all I need!
35%
 35%  [ 6 ]
Total_votes : 17

Author Message
jhecht


Joined: 29 Jan 2006
Posts: 153
Location: New York City (Manhattan)

PostPosted: Fri 26 Sep 2008, 14:19    Post_subject:  Re: better documentation!
Sub_title: related postings
 

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
Back to top
View user's profile Send_private_message Visit_website 
MU


Joined: 24 Aug 2005
Posts: 13644
Location: Karlsruhe, Germany

PostPosted: Fri 26 Sep 2008, 14:28    Post_subject:  

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

_________________
my recommended links
Back to top
View user's profile Send_private_message Visit_website 
jhecht


Joined: 29 Jan 2006
Posts: 153
Location: New York City (Manhattan)

PostPosted: Fri 26 Sep 2008, 15:22    Post_subject:  

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
Back to top
View user's profile Send_private_message Visit_website 
WhoDo


Joined: 11 Jul 2006
Posts: 4441
Location: Lake Macquarie NSW Australia

PostPosted: Fri 26 Sep 2008, 18:24    Post_subject:  

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

_________________
Actions speak louder than words ... and they usually work when words don't!
SIP:whodo@proxy01.sipphone.com; whodo@realsip.com
Back to top
View user's profile Send_private_message 
jhecht


Joined: 29 Jan 2006
Posts: 153
Location: New York City (Manhattan)

PostPosted: Fri 26 Sep 2008, 18:41    Post_subject:  

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! Smile

_________________
John Hechtman
www.zenarrow.com
jhecht@ix.netcom.com
"Computer help in NYC"
917 628 0192 - cell
Back to top
View user's profile Send_private_message Visit_website 
Lobster
Official Crustacean


Joined: 04 May 2005
Posts: 15117
Location: Paradox Realm

PostPosted: Fri 26 Sep 2008, 19:47    Post_subject:  

Quote:
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 Very Happy

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?

_________________
Puppy WIKI

Edited_time_total
Back to top
View user's profile Send_private_message Visit_website 
WhoDo


Joined: 11 Jul 2006
Posts: 4441
Location: Lake Macquarie NSW Australia

PostPosted: Fri 26 Sep 2008, 23:08    Post_subject:  

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! Smile

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.

_________________
Actions speak louder than words ... and they usually work when words don't!
SIP:whodo@proxy01.sipphone.com; whodo@realsip.com
Back to top
View user's profile Send_private_message 
battleshooter


Joined: 14 May 2008
Posts: 1111
Location: Australia

PostPosted: Sat 27 Sep 2008, 02:21    Post_subject:  

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 Smile
Back to top
View user's profile Send_private_message 
ttuuxxx


Joined: 05 May 2007
Posts: 10843
Location: Ontario Canada,Sydney Australia

PostPosted: Sat 27 Sep 2008, 06:52    Post_subject:  

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 Smile
Back to top
View user's profile Send_private_message Visit_website 
big_bass

Joined: 13 Aug 2007
Posts: 1747

PostPosted: Sun 28 Sep 2008, 00:27    Post_subject:  

Quote:

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
Back to top
View user's profile Send_private_message 
darrelljon


Joined: 08 Apr 2007
Posts: 548

PostPosted: Sun 28 Sep 2008, 08:12    Post_subject:  

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.
Back to top
View user's profile Send_private_message Visit_website 
bill

Joined: 28 May 2008
Posts: 495

PostPosted: Sun 28 Sep 2008, 10:37    Post_subject: 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 " Rolling Eyes "
Thanks big_bass
Back to top
View user's profile Send_private_message 
bones01

Joined: 11 Aug 2008
Posts: 371
Location: Melbourne, Aus

PostPosted: Sun 28 Sep 2008, 20:53    Post_subject:  

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.
Back to top
View user's profile Send_private_message 
bill

Joined: 28 May 2008
Posts: 495

PostPosted: Mon 29 Sep 2008, 10:38    Post_subject: 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. Very Happy 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 Crying or Very sad 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
Back to top
View user's profile Send_private_message 
stevesr0

Joined: 24 Jun 2007
Posts: 169

PostPosted: Wed 01 Jul 2009, 22:11    Post_subject:  

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
Back to top
View user's profile Send_private_message 
Display_posts:   Sort by:   
Page 1 of 2 Posts_count   Goto page: 1, 2 Next
Post_new_topic   Reply_to_topic View_previous_topic :: View_next_topic
 Forum index » Advanced Topics » Puppy Projects » Documentation Project
Jump to:  

Rules_post_cannot
Rules_reply_cannot
Rules_edit_cannot
Rules_delete_cannot
Rules_vote_cannot
You cannot attach files in this forum
You can download files in this forum


Powered by phpBB © 2001, 2005 phpBB Group
[ Time: 0.1024s ][ Queries: 14 (0.0063s) ][ GZIP on ]