[Scummvm-devel] Documentation

[Max Horn]

Hi Henry, hi all,

my personal goal always was to keep the DocBook manual alive, and  
simply convert the Wiki manual back to DocBook at some point (or some  
other comparable format, should that meet a better reception by my  
fellow devs, that is).


Am 20.12.2007 um 21:44 schrieb Henry Bush:

> OK, I've been thinking about this on my walk home.
>
> Why did the manual get moved (or copied) to the wiki in the first
> place? I suspect (though I wasn't involved in discussion, correct me
> if I'm wrong) in order to try and promote it, and to get more people
> contributing.

That was precisely the reason. It was an experiment.

>
> The only benefit to having the manual on the wiki that I can see is
> that it's easier to edit, and that doesn't seem to have made any
> difference to the number of people contributing.

But it did! The DocBook manual has been around for almost exactly  
three years now. And there were very very few contributions by people  
other than me. And now we do have quite some activity. So in my eyes,  
there is quite a big difference.

The hope is to get more people "hooked". Once they are in, we can  
still try to convert them to proper DocBook authors *g*. Or, for that  
matter, convert what they wrote to DocBook at some point (that is,  
first finish the manual in the wiki, then turn it into DocBook, and  
maintain that).

Maybe if we posted a news item about this, and actively ask for help  
on the forums, we get additional "real" contributors. Maybe not...

> On the other hand,
> the benefits of a docbook (or similar) manual are huge: easy
> conversion to almost any format (including multi-page html), easy
> creation of multiple documents for different purposes (e.g. different
> readme for different ports, etc), and I'm sure there are others.

Yes to all :). That was one of the reasons to go with DocBook in the  
first page.

>
> I don't want to come across dictatorial (especially where I have
> absolutely no place to be), but what do people think about the
> proposal of scrapping the wiki manual and switching back to docbook?
>
> There may be a little content overlap with the wiki, but with suitable
> links, both wiki->manual and manual->wiki, I think we can minimize it.

Sure..


Bye,
MAx