Re: documentation for novice and newbies
On Wed, Feb 07, 2007 at 09:58:16AM -0500, hendrik@topoi.pooq.com wrote:
> On Tue, Feb 06, 2007 at 05:30:10PM -0500, Douglas Allan Tutty wrote:
> > Hi all,
>
> > 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.
> >
>
As far as these discussions go, we should probably move to debian-doc
since this discussion isn't about, directly, solving users' problems.
What say ye? If this seems reasonable, let me know and I'll post this
whole reply as you see it over to debian-doc (this saves debian-doc from
receiving this from _all_ of us).
> 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.
Yes, sorry, I forgot that. This then gets us a hook to be seen by a
search engine and a link on something that newbies to debian.org will
see.
> > 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.
>
Sorry for the obscurity. I didn't want to say that they can do without
a desktop environment because they don't know any better. I meant that
they should go without a desktop environment and focus on
CLI/aptitude/lynx/mc skills first.
> > 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.
That was a problem in the documentation. I want to provide
documentation so that the reader of the instalation manual _will_ know
what the installer means.
>
> >
> > 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.
Answering this myself, it seems that wikis are flat in that all pages
are under the one main wiki, but any page can reference any other page.
However, if we went with multiple pages, scraping it all off and
combining it into a stand-alone html doc could be a problem.
> I think nano is the one Debian currently prefers for rescue disks and
> the like. Its big advantage is that minimal documentation is
> available at the bottom of the screen.
Yes. I used it for a while before I learned vim.
> > 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.
If they're used to it. Each of us has a different focus, which is good.
Mine is the novice who isn't used to anything.
> >
> > 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.
>
A couple of problems with using versioning/docbook, that probably have
solutions but I'm unfamiliar with both: I'm on a slow dial-up line.
With versioning does that mean that I grab the current version, download
it which locks others out of grabing it, edit it, then upload the new
version? That cycle could take a while and tie up the document.
I _think_ that a wiki makes this a lot faster. It allows us to generate
html. However, it makes it difficult to break it up into small
documents and link them together again, and to make other formats.
> 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.
LGPL always talks about libraries even though the first L is for Lesser.
What use of our documentation would be curtailed by using the GPL? It
looks to me like it can be copied verbatim or modified and kept GPL. It
could be copied into a book and sold at media cost and kept GPL. It
could be incorporated into a book and our stuff would be GPL while the
book's author's work would be under whatever licence they choose. Our
stuff in all cases remains under GPL. I would suggest that the document
(wiki or otherwise) be set up just like any other GPLd document on
debian with a clear copyright statement.
>
> 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.
We can also tell them how to do homework after they get the
recomendation from the computer store to have an idea of any problems
before they buy.
Thanks all.
Doug.
Reply to: