NOTE: I'm moving this to the dev list to save the non-dev people from reading this.
On Fri, Jul 10, 2009 at 2:43 PM, Marvin Addison <marvin.addi...@gmail.com>wrote: > > I'm not really sure we want the Steering Committee being in charge of > this. > > Clearly I disagree. Documentation, like design, benefits from a > small, focused team of individuals in charge. I don't think I said anything to the contrary. But our steering committee isn't in responsible for the design of CAS. They're responsible for the governance of CAS. My point is that appropriate set of people should be reviewing the documentation, just like an appropriate set of people guide the design/architecture of CAS. That would imply people with experience or an active interest in gaining that experience. > It seems entirely > feasible to me that the Steering Committee could conduct an annual > review of the wiki, post a "todo" list of changes needed, and request > volunteers to actually make the edits. Whether or not volunteers take > up the content change tasks, the review would produce tangible > documentation for areas of improvement. And I would suggest we identify a new documentation coordinator with documentation experience to handle that because its more than just doing a gap analysis. Its structure, organization, word choice, etc. We used to have a documentation coordinator and while he was a nice guy, wasn't exactly the most effective. Its also the development team's responsibility (and unfortunately that means mostly you and I ;-)) to make sure anything we adding thing we code gets documented. > > > we'd only want to bring it to the Steering Committee if there were > > major quality control, lapses, or issues > > The wiki suffers from some organization problems and incomplete and > conflicting content. It started out organized when it was only me writing documentation ;-) But clearly just having one person isn't a viable solution unless we pay someone. > It's a matter of opinion whether the details of > those problems constitute a major quality control problem. Given a > feasible process for correcting those problems, we should doubtless > correct them. My proposal for annual review by the Steering Committee > is one potential solution. Reviewing it annually is just as bad as not reviewing it at all (well, maybe slightly less bad ;-)). Reviewing change revisions of page changes for the past year will be no fun. I think we want the same end goal: better documentation, but having tried to go through this before I'm well aware of potential problems that will crop up with having the steering committee review it once a year. I think identifying someone with an interest in maintaining that content or trying to gain experience who can review it more frequently is a better solution. Now, I unfortunately don't have anyone in mind for that at the moment. Maybe Jasig needs to post available volunteer opportunities or reach out to member institutions that already rely on existing Jasig documentation to improve the documentation (we actually tried this once to various degrees of success). The documentation may need to be locked down and more controlled with regards to who can edit it in order to maintain quality (I'm not advocating that, but its also one possible solution) > It puts the decision making process in the > hands of a small number of qualified people, and that is a good thing. I think you give the steering committee too much credit. While we're all awesome people (honestly, really, we are), that doesn't make us the qualified people to review and maintain documentation. Now, yes, there's some obvious stuff that just about anyone, qualified or unqualified can catch, but I'd much rather see us bring back the documentation coordinator position (in whichever name we decide to give it) and have that person or a small team working with them the responsibility of maintaining documentation and working with volunteers to keep it up to date. After all that, to sum it up, I'd rather see more pro-active contributions from a qualified set of volunteers than a once a year review from the committee that would only catch minor infractions (i.e. the most obvious stuff). The make-up of the steering committee changes frequently enough (each year) that I'd be uncomfortable giving that task to the steering committee. One year it could be highly technical people who catch every missing feature documentation, but totally blow the structure/organization and in other years it could be the complete opposite. > > M > > -- > You are currently subscribed to cas-u...@lists.jasig.org as: > scott.battag...@gmail.com > To unsubscribe, change settings or access archives, see > http://www.ja-sig.org/wiki/display/JSG/cas-user > -- You are currently subscribed to cas-dev@lists.jasig.org as: arch...@mail-archive.com To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/cas-dev
