Re: documentation for novice and newbies

[hendrik@topoi.pooq.com]

On Wed, Feb 07, 2007 at 11:58:11AM -0500, Douglas Allan Tutty wrote:
> > 
> > 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.

 A distributed versioning system works like this.  You have your own 
copy of the repository.  You do all your edits, check-ins, and 
check-outs on that version.  Every now and then (in the middle of the 
night when phone rates are cheap, for example) you sync your repository 
with one of the others.  All the changes get sent back and forth, so 
afterward the repositories are the same.  If there are simultaneous
updates, the version control system merges them, unless there are 
serious incompatibilities, in which case, the changes have to be 
manually merged.  But this merging can also be done anywhere by anyone, 
and the merge gets distributed in the same way.

Good wikis actually store their repositories in a versioning system.  
If we were to find a wiki whose reporitory is distributed as above,
we could even have multiple wiki sites that keep their contents 
synchronised.  This would make the up-time for any specific wiki less 
critical.

-- hendrik