Re: documentation for novice and newbies

On Wed, Feb 07, 2007 at 09:58:16AM -0500, hendrik@xxxxxxxxxxxxxx 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.


--
To UNSUBSCRIBE, email to debian-user-REQUEST@xxxxxxxxxxxxxxxx
with a subject of "unsubscribe". Trouble? Contact listmaster@xxxxxxxxxxxxxxxx

Relevant Pages

  • Re: documentation for novice and newbies
    ... installer, its manual, their computer, and later their new installation. ... something like "For Novices and Newbies to Debian". ... Under this we could have individual wiki entries that we could work on. ... documentation for linux in general can be confusing when trying ...
    (Debian-User)
  • Re: documentation for novice and newbies
    ... I'm concerned about the newbiedoc wiki: ... so we can't get the debian ... As a whole its GFDL although we could do our page GPL. ... To UNSUBSCRIBE, email to debian-user-REQUEST@xxxxxxxxxxxxxxxx ...
    (Debian-User)
  • Re: -Crawl- -Stone Soup- Release Announcement (yes, Release Announcemen
    ... one person doing the documentation or that online thing. ... person") without using a wiki. ... but will mention any contributers in the credits (every ...
    (rec.games.roguelike.misc)
  • Re: Angband documentation project
    ... referring to off-line documentation. ... The documentation is mostly likely to be referred to immediately after ... This makes sense - however the Wiki edit history is probably easier to determine ... PDF, HTML etc. ...
    (rec.games.roguelike.angband)
  • Re: Angband documentation project
    ... Given that my plans involve making the help external HTML files (with ... Using a wiki isn't that great for this, ... the documentation is currently distributed as, ... helpfiles are probably GPL, though that's not really that appropriate ...
    (rec.games.roguelike.angband)