Darren Reed writes: > >That's why this is chartered as a project with a repository: it gives > >us a stable place to put these documents. > > > > So this might be thought of as two projects in one: > one to create a repository and one to deliver a single document.
Possibly, yes. However, as written, it's a project that has a repository and that has an initial task in its charter. Adding more tasks over time should be fairly easy and obvious. > >For what it's worth, it's modeled after the existing SMF documentation > >project: for exactly the same reasons. > > > > And is there any reason why we have to limit ourselves > to what they're doing? No. But it looks like a good model to follow, because the situation is similar. We have a set of programming interfaces that are private to the system, and thus ordinarily would not be documented, but that need some detailed documentation because there are others relying on them to deliver complicated software elsewhere in the system. Ultimately, I think it's possible that nearly all of these interfaces end up being stable. When that happens, the documents produced by this project should end up being contributed to a regular documentation repository. That'd be a normal project completion point. > >It sounds like you're saying that we aren't allowed to get started on > >our long-awaited detailed documentation simply because we're not > >proposing to document the world from the get-go. > > > > No, I don't want to see this project result in a one off effort. There's no way that I can force others to deliver documentation for private interfaces that they haven't seen fit to deliver on their own. I'm thrilled that the Nemo/GLDv3 folks want to contribute some higher-level documentation. I think that's great, which is why I offered to put together this proposal for a project to house that effort -- a place that allows the participants in the project to discuss the details of what they're doing, a repository to share their work, and an open location to coordinate any related work. > And I don't want to see this problem (documentation) forgotten > after the GLDv3 document is delivered. > > As you've recognised higher up, there is quite likely demand > for more documents than just this. At the very least, this > project should be able to say it will be responsible for adding > documentation for both the volo and pfhooks projects as they're > both aiming to deliver programming interfaces for networking in > the Solaris kernel. There may even be some work related to xbow > as well. I can't demand that those people deliver anything. If they want to contribute, then they're more than welcome to join this project and deliver their own bits. That'd be a great result for the community. However, I'm not going to speak for them. If they don't want to do it, then this project is *still* useful even without them. > If you want to call this the "GLDv3 Documentation Project", > then I'd be happy to say yes to what's proposed, but it's being > called the "Network Documentation" project, so I'm expecting > more than just GLDv3. To call this project "Network Documentation" > and just deliver GLDv3 documentation seems like some sort of cruel > joke that makes us look like fools (IMHO.) It's the home for what networking documentation folks are willing to contribute. If that's _just_ Nemo/GLDv3 and that's the only thing that ever shows up, then that's probably a sad commentary on the way we're doing engineering, but it's certainly far better than not having Nemo/GLDv3 documentation at all, and it's much better than producing that OpenSolaris documentation behind closed doors. > Other deliverables that should be considered: > - standard templates for use with staroffice and other > applications to facilitate ongoing production of > documents (or at least drafts) by project teams; > > - recognition that future projects that deliver APIs > into Solaris Networking can be considered incomplete > without a deliverable that includes a submission > into this archive. > > Is "Network Documentation" complete with just a GLDv3 document, > with or without a respository? No. And without scope to make > it complete, it is hard to find reason to +1 it as is. I think both of those demands are out of scope because none of the contributors to the project has expressed an interest in doing those things. Don't project contributors get at least some say in the scope of their projects? If someone wants to join the project and expand the scope to include those things, then that'd be great. I don't think the project is incomplete or lacking invalue without them, though. I'm really quite disappointed that a project proposal like this would meet with such opposition. Maybe what one of the senior folks commenting on this said was right -- that we shouldn't bother with the overhead involved in doing this on OpenSolaris, and should just cook up the documents on the SWAN, because we need them now, and the argument and delay required to get them going is not worth it. -- James Carlson, Solaris Networking <[EMAIL PROTECTED]> Sun Microsystems / 35 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677 _______________________________________________ networking-discuss mailing list [email protected]
