Peter Eisentraut wrote: > On Tuesday 28 July 2009 15:36:29 KaiGai Kohei wrote: >> Peter Eisentraut wrote: >>> On Sunday 26 July 2009 14:35:41 Sam Mason wrote: >>>> I'm coming to the conclusion that you really need to link to external >>>> material here; there must be good (and canonical) definitions of these >>>> things outside and because SE-PG isn't self contained I really think you >>>> need to link to them. >>> This is not supposed to be user documentation. It's supposed to be a >>> feature specification that an implementation can be validated against. >> Hmm... >> What kind of descriptions are necessary for a feature specifications? > > It describes what the feature does and why. > >> Currently, I guess the specification describes when/where the security >> hook should be invoked, what permission should be checked and what result >> should be returned for each security hooks. >> >> Is it correct? Or, do you expect any other stuffs? > > That is a pretty good start, but it's drifting into implementation details. > >> Apart from that, user documentation is also necessary. >> If the specification should be described from completely different >> viewpoint, I'll provide it. > > Yes, user documentation will eventually also be necessary, and the original > specification may be usable as a source for that. I'm just reacting to those > who commented whether or not references should be added and what reference > style the documentation uses. We're not there yet. The purpose of this > document is to explain what the feature does, not to teach users to use the > feature.
For a couple of days, I have paid my efforts to provide the design specifications more than user documentations. (But a few sections are under construction.) http://wiki.postgresql.org/wiki/SEPostgreSQL_Development Some of sections are copied from the SEPostgreSQL_Draft and edited, rest of sections are also revised to represent its feature and behavior more correctly. At the current moment, I can agree it is too early to discuss the style for user documentation. So, I would like to freeze the efforts to the user documentation for a while, and begin to discuss the design specification which focuses on developers. Thanks, -- OSS Platform Development Division, NEC KaiGai Kohei <kai...@ak.jp.nec.com> -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers