Re: documentation for novice and newbies

[Andrei Popescu <andreimpopescu@gmail.com>]

On Wed, 7 Feb 2007 11:58:11 -0500
Douglas Allan Tutty <dtutty@porchlight.ca> wrote:

> 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).

I just subscribed. I'm also cross-posting this to debian-doc.

> 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.

I was planning on writing a more general introduction to computers (OS
agnostic).

> 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.  

Concurrent versioning solves exactly that. You download a copy of the
file, edit it locally and then upload the changed file. If the original
file has changed the changes are merged if they don't conflict or you
get a notice and you can solve the conflict manually.

> 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.

I think the wiki should be our primary focus, then use the content from
the wiki to create other versions (html, plain text, ...) using cvs/svn
whatever.

Regards,
Andrei
-- 
If you can't explain it simply, you don't understand it well enough.
(Albert Einstein)