Developing novice/newbie installer guide

[Chris Lale <chrislale@untrammelled.co.uk>]

Douglas Allan Tutty wrote to debian-user@lists.debian.org:
> On Wed, Feb 07, 2007 at 03:00:05PM +0000, Chris Lale wrote:
>   
> > Douglas Allan Tutty wrote:
> >     
> > > If we were to have a page clearly labled as GPL, would you be able to
> > > spit out an html of a wiki page any beter than we could pull off with a
> > > browser?
> > >       
> > I
> [...]
>
> What I mean is that if we create a main wiki page with a separate wiki
> page for each major portion of the project instead of one HUGE wiki
> page, I can't get wget to follow links in the wiki page to grab those
> other pages.  
>   

This is probably not what a wiki is designed for. It is not designed 
primarily to develop individual webpages for other purposes. The final 
product is the wiki itself.

Normally you link a family of wiki pages using this syntax:

   [[name-of-page-to-link-to]]

(see http://newbiedoc.berlios.de/wiki/Help:Wikitext_markup#Links).

In the case of NewbieDOC,  There is a page for each major section (eg 
"Articles", "Notes", etc) with links to the subsections (ie the 
articles). In NewbieDOC articles, a table of contents is generated by 
default (optionally with numbered headings).

> Take an example:
>
> 	MainPage(TOC)
> 		Chapter1-page
> 		Chapter2-page
> 		.
> 		.
>
> I can use wget or a browser on the TOC, Chapter1-page, and Chapter2-page,
> but I end up with three separate html pages not really linked (in fact,
> the links in the TOC still point to the wiki not the files I download
> with wget.
>
>   

You should probably use a webcrawler application such as harvestman or 
httrack rather than wget for this.

The magic of a wiki is that it does everything automatically - editing, 
rendering to html, version control, etc. Very little manual intervention 
is needed. It sounds that you envisage needing more control over the 
system than a wiki provides, and that the project will produce a single 
large work much in the manner of the Debian Reference manual - 
effectively a book rather than an article.

The wiki approach is aimed more at being accessible to people who have 
only writing skills. Other approaches will probably need contributors to 
have, or to develop, some technical skill in areas such as editing, 
rendering to html, version control, etc.

Ultimately, the minimum outcome will be HTML (chunked or non-chunked); 
probably PDF and text versions too. I would suggest that this is how the 
alternatives compare.

_Wiki_
   easy to edit with GUI or console browsers
   automatic rendering to HTML
   critical items can be protected from editing whilst still allowing 
comments, thus squashing bugs fast.
   automatic version control
   internal messaging system, email and RSS
   pages added automatically to website

_DocBook SGML/XML_
   best edited with console apps such as Emacs or Vim with the 
appropriate plugins
   need to learn markup unless exporting from OOo or LyX (GUI only)
   SGML/XML tools to render to HTML, PDF, text, etc
   SGML tools are still probably better than XML tools
   external version control and development mailing list needed to 
manage the project
   website managed separately

_OpenOffice.org_
   Open Document Format
   X needed
   no markup to learn (WYSIWIG)
   can export to DocBook, HTML, PDF, text, etc
   external version control and development mailing list needed to 
manage the project
   website managed separately

_Lyx_
   X needed
   no markup to learn (WYSIWYM)
   various document classes including article, book, docbook
   can export to DVI, DocBook, HTML, PDF, text, etc
   external version control and development mailing list needed to 
manage the project
   website managed separately

HTH,

--
Chris.