[postgis-devel] Making PostGIS documentation process easier

[Paragon Corporation]

I like the user comments idea.  As I recall, I think PostgreSQL uses DocBook
format as well and having a way for people to add comments at the end of
each reference function would be nice.

Pierre -- to add to what Olivier is saying.

The thing I like about DocBook is that its very structured, much more so
than wiki.  Then I'm in the database business because I'm a control freak
who is extremely lazy :).

a) This allows us to be able to autogenerate the postgres help comments
directly from the manual with a script.  Which is useful for quick help in
psql or PgAdmin

b) It also allows for autogeneration of test scripts and so forth from the
signature of the functions 
C) It also allows for cross check.  E.g. if the postgres help doesn't
install, I know the documentation is wrong, or Paul broke something by
deciding he wanted to rename a function or delete it :)
D) It also allows for other kinds of things like the autogeneration of the
matrix of functions and all the MM compatibility, what's new sections are
all autogenerated.  - basically the whole chapter 8

http://www.postgis.org/documentation/manual-svn/ch08.html

So in short there is a lot of autogeneration of indexes and so forth, that I
don't think would be possible or at least not as easy without a pure xml
format.  I also feel that Official documentation needs to be very structured

and enforce a strong level of consistency to be taken seriously which means
it can't be done by a huge committee or many hands without some level of
approval.  I guess I'm old fashioned in this respect.

Thanks,
Regina

-----Original Message-----
From: postgis-devel-bounces at postgis.refractions.net
[mailto:postgis-devel-bounces at postgis.refractions.net] On Behalf Of Olivier
Courtin
Sent: Thursday, June 24, 2010 3:50 PM
To: PostGIS Development Discussion
Subject: Re: [postgis-devel] Making PostGIS documentation process easier


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
_______________________________________________
postgis-devel mailing list
postgis-devel at postgis.refractions.net
http://postgis.refractions.net/mailman/listinfo/postgis-devel