Joseph Kowalski writes: > Gee, keep hitting return too early... > > James Carlson wrote: > > All correct, but "documented" doesn't always mean man pages. It does > > for "Committed" interfaces, but those at other stability levels can > > use whatever's appropriate -- white pages, READMEs, blogs, et cetera. > > > For Solaris, it actually does mean man pages. It may be a vestigial man > page (an > example of which I sent out this week on a different thread), but a man > page none > the less.
I'm not sure I completely agree. Our taxonomy says this under Uncommitted: "In some situations, it may be appropriate to document Uncommitted interfaces in white papers rather than in standard product documentation." I've always understood this to mean, "for experimental items, it might be better to document them with non-official documentation, to avoid accidentally conferring the sort of legitimacy that official documentation has." An interface that's intentionally just temporary and will be used as an expediency until something better's designed sounds to me like an interface that should at most say "see XREF" in the man page. Oddly, though, we demand man page entries for Volatile. (Perhaps we're saying nearly the same thing. "X exists, but no more information is available about it here" to me isn't exactly documentation.) -- James Carlson, Solaris Networking <james.d.carlson at sun.com> Sun Microsystems / 1 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677
