On 3/15/07, Peter Memishian <[EMAIL PROTECTED]> wrote:
> > * Needs to be easily editable. > > * Needs to be reasonably compact. (To ease remote development) > > * Needs to have a reasonable facility for drawing diagrams. > > Would a wikimedia-type wiki page be sufficient? I'm confused. A wiki page that lives in the source tree?
Perhaps that makes it easier. Since the wiki will automatically do revision control, you could likely just add a comment in the code to the particular revision of a wiki page (not the latest version, but the version that corresponds to the design on that page). Suppose you are working on a PAM module (that's redundant) that integrates Solaris with Active directory. Closely related to this is a project to give per-user CIFS mounts (with private namespace per user) so the security model seems to resemble Windows[1] but better because the namespace isolation is done with TX. In the case of documentation living with the source, you would need to have docs scattered through[2] pam_modules, nsswitch, fs/cifs, tsol, etc. Figuring out what goes where and stringing the story together would be extremely complex. Instead, if you could just add links to the top of the relevant source file or even to the relevant functions, those interested in the design could be quickly pointed to the right docs. Those docs can be appropriately cross-linked within documentation and back to the source code. 1. Yeah, that sentence sent shivers down my spine too. 2. Likely fake directory names based upon foggy memories of digging through the source over time. As an off-topic thing to discuss in the future, should OpenSolaris fault diagnosis messages point to sun.com or a wiki on opensolaris.org? Should debug builds point at detailed pages designed for people with a coding background and non-debug point to end-user pages? Mike -- Mike Gerdts http://mgerdts.blogspot.com/ _______________________________________________ opensolaris-code mailing list [email protected] http://mail.opensolaris.org/mailman/listinfo/opensolaris-code
