[postgis-devel] Making PostGIS documentation process easier

[Olivier Courtin]

On Jun 24, 2010, at 9:05 PM, Pierre Racine wrote:

Hi,

> I know I will ennoy some people here but it seems to me that we  
> would gain a lot by making the PostGIS documentation wiki style. We  
> could benifit more from the community experience and be able to  
> update it more quickly and frequently. What are the pros of keeping  
> the documentation process that closed in the source tree in obscure  
> XML comparing with open wiki pages?

Docbook is an abstract format
So you could convert it (quite) easily to something else
like XHTML or PDF or (quite) anything else you want.

I'm not sure that a wiki is able to do thing like that

And Wiki are not open,
i mean that it's not an open standard
there's a plenty of wiki syntax...

Wiki is just simpler,
And if you want a simpler way,
you could copy/paste other part of the doc to get the grammar
put your documentation stuff
and use 'make check' rule to be sure that your doc is clean


> Seems to me that since the appearance of wikis, fixed, closed  
> documentations are very much old fashion and look like death things.  
> Right now I think only one person is maintaining the doc. We could  
> be more if it would be easier.

Regina and Kevin done an huge work to rewrite
the doc and to maintain it since 1.4
And i like the idea to have an official doc.

But i'm agree with you,
maybe there's a lack for user comments feature
like in PostgreSQL doc for instance,
http://www.postgresql.org/docs/8.4/interactive/index.html

>
> I know one of the argument is that each release need its own  
> documentation since updates apply only to certain releases but to me  
> this is not incompatible with a wiki. We can have one versions of  
> the doc per release still in wiki style.


My 2 cents,

--
Olivier