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 <kaigai@ak.jp.nec.com>