[linuxkernelnewbies] How to succeed with an Architectural review at OpenSolaris.org

[Peter Teoh]

http://opensolaris.org/os/community/arc/arc-faq/arc-review-advice/ How to succeed with your review Compiled by David Kahn, July 2001 We've seen many ARC cases that come for a review with incomplete or poorly written project case materials. These projects create a lot of work for the committee, the case owner and can lead to a lot of frustration on the part of the project team and cause the team to spend a lot more time getting their project approved. Here's some suggestions to help projects along: Do your homework. Make sure you know your material and that you have done all the prerequisite work for coming to ARC. This includes a working prototype. I can't stress this enough. Make sure you are presenting clear, concise architecturally sound interfaces that are written properly. Many cases don't bother to write interface descriptions that are clear and sound. A sound definition defines the interface, the arguments, the results and describes what the interface does, and need not describe the implementation. Somebody unfamiliar with your project should be able to understand the interface from its definition. The ARC does not want or need to be in the business of teaching project teams how to write clear definitions. We have enough work to do already. Learn the difference between architecture, design and implementation. The ARC is concerned with architecturally sound projects. The ARC doesn't care if your project has to ship in a day. That's your problem. In fact, if you waited this long, that's an indication that your project already suffers from poor planning, so that's already one strike against your project. The ARC is not there to solve your disagreement. You should go off and try to reach consensus on your own before coming for a review. Sure, on the face of it, ARCs are chartered to help resolve disagreements, but do you really want to do this in front of the ARC and show that you are incapable of reaching consensus on your own? In the past we have refused to do this and I expect that we will refuse to do this in the future. Why? We find enough things to argue about by ourselves. Make sure that your project is really solving the right problem. Don't bring us an obvious hack which doesn't solve anything except your immediate problem for your project that was supposed to ship yesterday. If you are proposing a bus binding or a new device node definition for FWARC, write the proposal properly as a bus binding or a device node definition using the forms used by OFWG and several FWARC cases. The basic format of these things was defined by OFWG over five years ago .. there's really little excuse to not follow it. Ask for help reviewing your case before you submit it. I've done this time and again, and my projects seem to sail right through PSARC every time. I ask the right person, and listen to their advice, even if I don't necessarily agree with it. If I can't defend my position with the person I asked for review help, then there's probably a real problem. Doing this before the ARC review is a huge help. In the end, the ARC meeting ends up being a mutual admiration meeting rather than an hour long argument. Don't piecemeal the ARC to death. Certainly, there are some times when an interface can be separated out and fasttracked separately, but we really don't need a dozen separate cases for a project when one will do. (But it better be one sound case and not one case with a dozen problems.) If you have trouble writing architectural definitions, get help before you go to ARC. It's not our job to write for you. If you can't do this on your own, perhaps this line of work is for somebody else? If your project doesn't get approved at the inception review, don't panic .. work efficiently and quickly with your case owner to resolve all the open issues and resubmit your materials for committment review AS SOON AS POSSIBLE. The worst thing to do is to let a case drag on endlessly because then we're going to forget the discussions we had the first time around and do that all over again at the committment review. References are great, but don't expect ARC to be able to comprehend a complex 100 - 300 page specification for your project review. ARC members are busy .. just give us the pertinent facts in the case materials and include the references to the complex documents for case documentation. Make sure you are solving the real problem and not proposing an implementation full of holes. The term "But it's a marketing requirement" should be banned from ARC meetings and project requirements. Marketing requirements are created by marketing, not engineering, based on their perception of market requirements and conditions. Engineering has a great deal of input into the design and architecture of platforms based on requirements. If a platform hasn't been designed from the ground up to support its requirements, it may be difficult to impossible to retrofit them at a late date.