Documentation

What features/apps/bugfixes needed in a future Puppy
Post Reply
Message
Author
newphil82
Posts: 8
Joined: Tue 19 Feb 2013, 07:48

Documentation

#1 Post by newphil82 »

This may sound silly, but ... ? A long time ago I was working and had to produce technical "how-to" docs. Results were fairly useless - until I managed to recruit some "guinea-pigs" who could give me intelligent feedback on WHY they were misled or confused. After that, my 'public' didn't moan quite so much!

Am I just slower than average on the uptake, or would Puppy and Linux in general be more popular if there was more "trying it out on the dog" before certain key documents were published? I know from experience that it's a bit of a pain - but I think a lot of folk are put off linux etc because the intros make their heads ache. OK, I mean they make MY dull head ache a bit!! --- But I love Puppy Linux andd want to get on!

User avatar
darkcity
Posts: 2534
Joined: Sun 23 May 2010, 19:16
Location: near here
Contact:

#2 Post by darkcity »

to my knowledge there aren't many documents published online or offline. the introduction is here http://puppylinux.com/

feed back is always the most useful thing. 8)

nooby
Posts: 10369
Joined: Sun 29 Jun 2008, 19:05
Location: SwedenEurope

#3 Post by nooby »

I am too different to be of any help.
But I have failed to follow such texts since
around 1986 when I got my first IBM clone
from Taiwan I read about msDOS and DrDOS
and similar OS I tried to learn them and failed.

then fast forward to around 2003 the first CD
with Linux that came with the PCWorld Mag
here in Sweden may have existed earlier in other countries.

I did not get it. Then 2006 Ubuntu CD that was free
one could go to a Computer Shop and get one.

I never understood that permission thing and
felt for giving up on Linux until 2008 when I found
a link to Puppy linux and I asked and asked and asked
and it took me many months of daily participating in the forum
for to get it going at all. Then due to bad luch had two computers
that Puppy did not shut down in a good way had to wait until
2009 or 2010 before it worked well?

So around 2010 I decided to abandon Ms Win and do only Linux
but I still can not understand permissions.

But I think the OP is right about that one need true beginners
and record every error them make and then change the description
until it works with new total newbies. One can not reuse the old noobies.
They learn too fast :)
I use Google Search on Puppy Forum
not an ideal solution though

markreaves
Posts: 41
Joined: Sat 11 Sep 2010, 21:50

#4 Post by markreaves »

My observations from a neutral standpoint is that over 90% of documentation that exists concerning anything related to linux is wrote by and seemingly for Linux nerds/technologically well educated.

I personally believe that this is why "noobs" tend to try Linux hate it and go back to Windows. Seems many always say to read the docs for answers but the docs might as well be in another language.

MY suggestion is "example driven" documentation. Documentation that shows the new user how to do things using examples then explaining what they are doing. Screencasts/videos would be useful with this (with audio narration). For text documents it can still be done.

For example with configuring wifi on Puppy. There should be a screencast video for each version showing how to do it using DHCP and setting static IP and various other things related to getting wifi up and going. Would help new users more than just giving some string of commands to try or trying to explain how to work through the setup screens.

User avatar
Tote
Posts: 237
Joined: Thu 19 Jan 2012, 07:53
Location: South Wales

#5 Post by Tote »

I tend to agree to some extent. Even when it's 'dumbed down' I often find myself wishing it was 'dumbed down' just a little bit more so that I could understand it a little easier.

Documenting anything takes a lot of work; try to explain in words to someone who has never made a cup of tea the instructions for making one. It can require an awful lot of words. When it's something technical it gets even harder.

I've been using Puppy Linux for just over a year. I don't use anything else now, but I'm not a very demanding user; word processing, music, photos, browsing, that's about it.

There are a lot of things I don't understand. I still haven't figured out how to unpack and compile a tar file!! I suppose if I really wanted to I could get my head around it, it's one of those things I tend to put off until another day. That's sort of the story of my life, ( never do today what you can put off 'til tomorrow), but I like using Puppy, I wouldn't change to anything else.

Aside from the documentation issue I think what is off-putting to some new users are all the pre-installed options that appear when you right-click the desktop. Most of that stuff, I still don't know what it is. I can't even imagine a situation when I'd want to use something called 'gHasher calculate file hashes' or 'XArchive achiver'. It's all there for a reason but for a newcomer it all looks pretty overwhelming.

I think a stripped down, fully functional Wary or Precise, (or whatever), that boots straight to desktop, (with something a bit more eye-catching than jmw for a window manager), with pre-installed browser/flash/word pro/image viewer/music player/etc, (just the basics) and with 90% of the menu stripped out, (hidden), to avoid any confusion would attract a lot of new users.

Of course, you'd still need to consider the documentation issue.

It's all a learning curve. Part of the pleasure of using Puppy for me is figuring out how to do something I couldn't do before. Sometimes it's like a little light comes on inside my head; 'so 'that's' how you do it!' And sometimes the light never does come on. Part of it also actually 'remembering' how I did it too, but that's another issue.

For individuals, and for encouraging other newcomers to Puppy, it's going to depend on how much effort they want to put into getting it to work. Will they stick with it or go look for something easier?

For me, dumb it down, then dumb it down some more. (Homer Simpson??)

topaz
Posts: 132
Joined: Thu 14 Dec 2006, 20:18
Location: Northumberland UK

#6 Post by topaz »

i
I have been teaching puppy for 7 year as my job as a linux educator 10 to 75 year olds.
I just use picture led tutorials but have to make them and every puppy its different.

One of the problems is in the forum
PLEASE put the puppy version you are talking about at the top of each post or i find the post is for puppy 412 when looking for 528.

I am working on a graphic lead tutorials for 528-005 but have to do about 20 pdfs. grouped as to puppy version.
Where do i post these so people will find them as we dont have a central site.
I was thinking of the wiki with a link to a download site.

Suggestions required

User avatar
Moose On The Loose
Posts: 965
Joined: Thu 24 Feb 2011, 14:54

#7 Post by Moose On The Loose »

topaz wrote:i
I have been teaching puppy for 7 year as my job as a linux educator 10 to 75 year olds.
I just use picture led tutorials but have to make them and every puppy its different.

One of the problems is in the forum
PLEASE put the puppy version you are talking about at the top of each post or i find the post is for puppy 412 when looking for 528.

I am working on a graphic lead tutorials for 528-005 but have to do about 20 pdfs. grouped as to puppy version.
Where do i post these so people will find them as we dont have a central site.
I was thinking of the wiki with a link to a download site.

Suggestions required
How about this for a wild idea:

-Make the document HTML
-Add just a bit of JavaScript
-Up at the top of the document place a entry for the version.
-When a version is entered, select which set of pictures to use
-Use thing.innerHTML to deal with major changes

Post Reply