Re: documentation for novice and newbies
On Tue, Feb 06, 2007 at 05:30:10PM -0500, Douglas Allan Tutty wrote:
> Hi all,
>
> We've got lots of ideas flowing. Rather than reponding to each post (I
> was away for one day and there's a lot on this thread), I'll try to
> repond from my perspective to some of the points. In no particular
> order:
>
> I have been subscribed for a couple of weeks to the debian-www list
> (which is where the web site says to post comments on the website, sort
> of a 'webmaster' substitute), but haven't had any traffic really. There
> doesn't seem to be interest in updating the website to add a NOVICIATE
> button. Whatever we do, I think we need to have a clear title entry so
> that it can be found by google (however one does that).
>
> I have also been subscribed to the debian-doc list which is extremly low
> volume (probably a symptom of why we're having to have this whole
> conversation). If we felt we needed our own list to take some noise out
> of debian-user we could probably go there.
>
The discussion at
http://lists.debian.org/debian-doc/2007/02/msg00025.html
seems to say to go ahead and create the site (wherever) and they'll
consider linking to it if and when it's viable.
> I don't want to "dumb down" the debian project. I don't want to change
> the installer or its manual. I'm suggesting that we need a manual or
> equivalent, a companion document to help the novice understand the
> installer, its manual, their computer, and later their new installation.
>
> A novice can certainly go without a desktop environment since they don't
> know any worse.
I'm not sure what it means to not know any worse, nor how it
relates to going without.
> A newbie (person with previous other OS experience) has
> more to unlearn so may feel that they can't live without one. This is
> fine. Our manual can give a choice by giving some background. The
> reader can make a choice when they run the installer (at the tasksel
> point in Etch's installer, they can choose desktop environment).
The first time I had this choice, I didn't know what the installer
meant with the term "desktop environment", although I have had
experience with Windows, X, Linux, and Unix all the way back to the
70's.
>
> I haven't signed up to be able to submit to the debian wiki
> (wiki.debian.org), has anyone else?
Yes. Just now.
> Is it flat, or could we set up a
> high level link, something like "For Novices and Newbies to Debian".
> Under this we could have individual wiki entries that we could work on.
> One of which could be a link to newbiedoc because, as I understand it,
> newbiedoc as a whole is unable to change its licence to GPL from GFDL to
> make it possible to just migrate it to wiki.debian.org.
It's obscure just what wiki.debian.org's licence terms are, because
the copyright page is missing, even though there are abundant links
to it. There are hint that each page belongs to whoever contributed
and/or edited it.
>
> My personal goal in all this is to turn people in to full-featured
> newbies. Newbies who know that:
>
> there is no _one_ definitive source of information on linux in
> general or debian specifically;
>
> much documentation for newbies is not an official part of
> debian.org;
>
> documentation for linux in general can be confusing when trying
> to apply it to Debian;
>
> entries under the wiki are the responsibility of the people who
> wrote it not debian.org (check the official wording on the
> wiki.debian.org home page);
>
> prior to installation, they need to read the installation
> manual.
>
> if they don't have a document that provides the infomation they
> need, their best souce is to google site:debian.org (will this
> give results from wiki.debian.org _and_ lists.debian.org?);
I just looked for
site:debian.org Finding where to start can be a daunting task
and found results in wili.denbian.org, people.debian.org,
planet.debian.org, lists.alioth.debian.org, utnubu.alioth.debian.org,
lists.debian.org on the first page. So, yes, it does.
>
> and can do the following:
>
> basic shell skills (not scripting).
>
> Use one of the editors that goes under /bin not /usr/bin (so
> they can fix something that keeps /usr from being mounted), like
> nano-tiny.
I think nano is the one Debian currently prefers for rescue disks and
th like. Its big advantage is that minimal documentation is
available at the bottom of the screen.
>
> Use Midnight Commander (mc) to explore the file system, read
> compressed documentation (e.g. under /usr/share/doc).
>
> man, apropos.
>
> Use Lynx to browse the wiki and do google searches.
Though a graphics-enabled browser is much easier to use -- you might
mention that they can, if they need to, browse from another machine.
Or, just to allay fears that this is *all* Debian can do, mention
that it *is* possible to install a images-and-mouse browser, like the
one they're probably used to.
>
> Use mutt to send and receive email. This requires that they
> know how to find information on their system to help them get
> connected to the internet.
>
> Use aptitude interactively.
It took me a while to discover that there was a noninteractive way to
use aptitude!
>
> I would like to be aware that novices may be installing from two images:
>
> netinst.iso, so they will have to get on the net to get anything
> more than the base system.
>
> CD1, so they will have good docs they can install without having
> internet.
>
>
> It would be good to have a way of packaging up a snapshot of what we put
> on the wiki. I haven't tried yet, but can we wget a tree from the wiki
> and have it as an html document? From there it could be turned into
> postscript from IceApe and from that into pdf. This may be easier than
> learning something like debiandoc and figuring out how to put _that_ on
> the wiki. The html, ps, and pdf could then be packaged into a .deb.
I'd suggest using a distributed versioning system. I use monotone
myself because I'm impressed by the amount of careful design analysis
and, frankly, paranoia that goes into its design. Its intended use
pattern is to commit early and often but to certify as viable or
desirable later. But I'd be to hear arguments why others are better
or worse.
I'm in favour of using an open standard for our definitive file
format. The obvious one is docbook, since that is used by other
Debian documentation. We should at least confirm to applicable
international standards. We'd still need a mechanism (preferably
partly automated) to interface between the definitive format and
informal formats -- I don't think we can realistically ban
submissions or edits in other file formats. The Linux documentation
project accepts input in many formats -- we might ask them how they
do it.
Licence? it should be as free as possible, to the extent that we
have a choice. This probably means multiple licences, unless we
want to make it public domain (which allows anyone to hack it for
any purpose). To the extent we use GPL, we should probably use
LGPL instead, or even the wxwindows license.
> My concern with having newbies going along fine with a desktop
> installation is that when something breaks, they don't know how to do
> anything. It is especially difficult if X breaks. Lets face it, X
> breaks an awful lot more frequently than init=/bin/sh.
Yeah, Being able to work without X is essential.
>
> With that in mind, for package management I suggest interactive aptitude
> from the outset.
>
> If we do our job right, we should be able to give someone who hasn't
> seen a computer before:
>
> a computer that just barely meets the minimal requirements for
> Etch;
>
> Our documentation;
>
> The installation manual;
>
> Etch CD1 i386;
>
> an ISP account;
>
> and receive from them a successful installation report.
Also important, we need to be able give them a few pages that they
can take to a non_linux-cognisant computer store so they can tell the
guy behind the counter just what they need -- and don't need -- in a
computer.
>
>
> How does this sound?
Good.
>
> Doug.
-- hendrik
Reply to: