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.