PDA

View Full Version : Reading the Documentation



ventrical
October 17th, 2011, 10:46 AM
Tell a newbie to 'read the documentation' and .. forget it ! You most likely have lost an Ubuntu convert. Back , decades ago, when I was in university it was more or less prerequisite to read the documentation that were included with any programs or proceedures. With todays fast paced social networking concepts, point and shoot and and overall development of easy GUIs most people do not want to take up the high-end task of studying the documentation. They want to push through to the end result .. and that is to just get their PCs working!!

A good case in point is trying to explain to an end_user the difference between 'updating' and 'upgrading'. I have told many clients countless time not to click on the UPGRADE button of their AVG security program.. but sure enough.. they do. To tell them to read the documentation just sends them reeling.

When I do an Ubuntu install of Lucid 10.04 for a client I also have to remind myself that I have to baby sit that install. Telling people to read man pages or the documentation will only make for soured relationships. There is no easy way around this. As a tech with most of my experience in instructional development I realize that I can only accomplish this by being a power of example.

One thing I would like to itemize and that is that during my time in school we used to have PC lab classes where 4 or 5 of us would break off into groups. This increased our abilities to retain what we were learning a lot easier as if we were to set out on our own - so - again , here is the community concept in action.


But a negative case in point is a most recent thread where many of us beta tested the most recent version of Ubuntu (Ocelot). The community environ worked well, friends were made and some bonding took place .. then , suddenly, the forum was closed and along with that closure some of the bonding was also muted. I can understand, probably for economic reasons, the sake of progress , etc. why those forums get closed, but with those closures goes with it a lot of illumination.

So, we can see then that as an example during beta testing, in the community environment, end_users and ITs alike were all working on a level playing field, a common ground so to speak. I admit that even myself was more intrigued to read some of the documentation and study some of the sudo codes. So we can see that when an incentive is involved ( ie; community rapport, bonding) then much more learning goes on.

Perhaps the same incentives could be applied to encouraging persons to have the same sort of enthusiasms when filing bug reports - and also stressing the importance of this. it has to be explained to people that they are not some sort of slave working on a Turing Machine. There has to be an incentive. If not monetary incentive then a community incentive of sorts may suffice.

regards...

ventrical

MonolithImmortal
October 17th, 2011, 11:05 AM
Everything I learned about linux I learned by "RTFM". Honestly, if you aren't willing to read up you aren't going to get anywhere with Linux, at least at this point.

coffeecat
October 17th, 2011, 11:26 AM
then , suddenly, the forum was closed and along with that closure some of the bonding was also muted. I can understand, probably for economic reasons,

Point of information: no, not for economic reasons. The forum you were referring to was the "Oneiric Ocelot Testing and Discussion" forum. At its head was this:


This forum is for the discussion of the development of the next version of Ubuntu (Oneiric Ocelot). Oneiric is in development and will be released in October 2011.

The forum was closed when Oneiric was released, as had all the previous testing forums when those versions were released.

But if you want the friends and bonding, there's always the Precise Pangolin forum, but I see you're in there already! :wink:

lucazade
October 17th, 2011, 11:39 AM
If people is superficial and don't want to read documentation, well, we can't do anything to improve this situation. It doesn't take too much time to read a wiki or a howto, docs that require a lot of love and time only for who wrote them for the community.
It is a kind of respect try to read before blaming, ranting or asking help without a research.

I want to hope people read docs for every tools they use, was a pc or a car.
There is no knowledge without documentation.

ventrical
October 17th, 2011, 12:02 PM
@coffecat Thats all a moot point , but thanks anyways.:) I'm just trying to illustrate how difficult it is for some to take up reading the documentation. Some that are not so computer savvy, yet still like computering, may feel excluded. Perhaps some that may need an assistive technology.

In fact I may propose this in the other forum - take up building an assistive search app for key paragraphs in man pages for specific items. I tried this with MS Outlook Express - suggested that they develop a classic version for more senior users but they obsoleted it. I mean , not everyone is floating around with a pair of white headphones sticking in their ears, waving their fingers at a handheld droid like their the wizard of Oz or something. Some people got work to do! :)

red_Marvin
October 17th, 2011, 01:43 PM
...most people do not want to take up the high-end task of studying the documentation.

High-end? How is it a bad thing to require people to know what they are
going to do before they start?
You may be right when seeing it as an observation of the current state of
affairs, but I don't see fostering that kind of mentality as something good.

Also you seem to be mixing gui applications and man pages a bit, afaik it is
mostly cli stuff and programming oriented things that have man pages, and
they are appropriate for that, gui apps usually have other means of
documentation.

You are right in that building a community around a project is a key point
to getting things done though.

ventrical
October 17th, 2011, 02:20 PM
High-end? How is it a bad thing to require people to know what they are
going to do before they start?
You may be right when seeing it as an observation of the current state of
affairs, but I don't see fostering that kind of mentality as something good.

Also you seem to be mixing gui applications and man pages a bit, afaik it is
mostly cli stuff and programming oriented things that have man pages, and
they are appropriate for that, gui apps usually have other means of
documentation.

You are right in that building a community around a project is a key point
to getting things done though.

Yes.. but considering some of the elements I mentioned in context - there is a tending of a leaning away from traditional document study. It's more 'touch and move' in todays world. It's the old attitude of 'if it don't work - throw it out'. Ok .. this is progress. It's bound to happen. The internet is as the internet does - as F Gump might say. But if we look at , lets say, Moore's Law - every so often in given time period PC hardware will get smaller and smaller while being able to store larger and larger amounts of data - to this effect..(I forget off hand) - then flip it around to GUIs .. they keep getting sleeker and sleeker while end_users get more sedentary. I mean , perhaps this is part of the initiation process.. to be baptised into the Ubuntu conceptology one has to suffer the documentation. :) lol

So .. what I am propounding is .. . encourage people to read documents by giving them extra beans so to speak, or , stick a star on their forehead I mean ... isn't it about throwing that one starfish away .. "it's matters to that one, doesn't it?".. so persons are not only challanged to read the documentation, they are inspired.!.. and if this does not work then all that is left are excuses.

grahammechanical
October 17th, 2011, 02:34 PM
Has anybody seen the help document that comes as part of the install process? In 11.10 (as in 11.04) it is very good. It is update to date. If I was installing 11.10 for a friend I would fix that help document into the Launcher.

The Canonical people have put a lot of work in giving assistance to new users. There is the Take the Tour video on at Ubuntu.com

Regards.

ventrical
October 17th, 2011, 06:24 PM
The *upgrade* document is rather simple and self explanatory. There is a lot of good stuff out there to read.

https://help.ubuntu.com/community/OneiricUpgrades

and here is the install docs from ubuntumanual.org

http://ubuntumanual.org/guides/435/how-to-install-ubuntu-11-10-oneric-ocelot-an-ubuntu-installation-guide