Sig A&D - Documentation And Communication

SIG Architecture & Design Documentation and Communication of a Software Architecture David Meijers February 5, 2009

Documentation – Introduction (1/2) [ ] February 5, 2009 SIG A&D Siemens Four Views RUP / Kruchten 4+1 Image: Lack of agility

Documentation – Introduction (2/2) This is not about ADL’s (such ACME , Rapide, Wright, Unicon) [ ] February 5, 2009 SIG A&D System simple_cs = { Component client = { Port send-request; }; Component server = { Port receive-request; }; Connector rpc = { Roels { caller, callee}}; Attachments { client.send-request to rpc.caller; server.receive-request to rpc.callee; } }

Stakeholders (1/2) [ ] February 5, 2009 SIG A&D Designers (of interoperating systems) Set of operations provided and required and the protocols for their operation (interface). Requirements Engineers (customer representation) Negotiating and making trade-offs among competing requirements. Managers Basis for: 1) forming development teams corresponding to Identified work assignments, work breakdown structure, planning, allocation of project resources 2) tracking of progress Designers (of constituent parts) Resolve resource contention. Establish performance and other kinds of run-time resource consumption budgets.

Stakeholders (2/2) [ ] February 5, 2009 SIG A&D Architects Reasoning Implementation teams Provide “marching orders”, inviolable constraints (plus exploitable freedoms) on downstream development activities. Testers and integrators Correct black-box behaviour of pieces that must fit together. Quality assurance team Basis for conformance checking (for assurance that implementations have in fact been faithful to architectural prescriptions). Transfer Engineers (or Product line managers) If and by how much a new product family member is out of scope. Maintenance team Starting point for maintenance activities, revealing the effects of change.

Documentation guidelines Write from the reader’s point of view, not the writer’s Avoid unnecessary repetition Avoid ambiguity Use a standard format Record rationale Keep documentation current but not too current Review documentation for fitness of purpose [ ] February 5, 2009 SIG A&D

The Carnegie Mellon approach (1/2) Views and Styles Viewtypes How the system is structured as a set of implementation units (module viewtype) How the system is structured as a set of run-time interacting elements (component-and-connector viewtype) How software structures correspond to system structures (allocation viewtype) [ ] February 5, 2009 SIG A&D

Example: Module viewtype UML notation: Elements Relations Properties (of elements and relations) [ ] February 5, 2009 SIG A&D

The Carnegie Mellon approach (2/2) Styles Patterns of design decisions. Module viewtype: decomposition, layered, generalization Component-and-connector viewtype: shared-data, communicating-processes, client-server, pipe-and-filter Allocation viewtype: implementation, work assignment, deployment [ ] February 5, 2009 SIG A&D

Example: Implementation style Informal notation: [ ] February 5, 2009 SIG A&D

Process Create relevant views Document them Add documentation that applies to more than one view [ ] February 5, 2009 SIG A&D

So, what do we do specific for designers? [ ] February 5, 2009 SIG A&D Software Architecture vs Design What is Design? What is Software Architecture?

What is design? As a verb, design is the activity of making such decisions. ...the resulting decision space may be large and complex. As such, there is a science associated with design (empirical analysis can point us to optimal regions or exact points in this design space) as well as an art (... degrees of freedom that range beyond an empirical decision ...). [ ] February 5, 2009 SIG A&D As a noun, design is the named structure or behaviour of a system whose presence resolves or contributes to the resolution of one or more forces on that system. A design thus represents one point in a potential decision space. A design may be singular (representing a leaf decision) or it may be collective (representing a set of other decisions ). Grady Booch

What is software architecture? "Architecture" is a term that lots of people try to define, with little agreement. There are two common elements: One is the highest-level breakdown of a system into its parts; the other, decisions that are hard to change. Martin Fowler [ ] February 5, 2009 SIG A&D All architecture is design but not all design is architecture. Architecture represents the significant design decisions that shape a system, where significant is measured by cost of change. Grady Booch

No project is the same The role of an architect is highly contextual But, the architect gets to define it Pick the relevant views, the stakeholder will help [ ] February 5, 2009 SIG A&D 

Communication – Introduction Don’t you just hate it when an architecture is stuffed down your throat? Does the architect ever talk to you? Who is the architect anyway? [ ] February 5, 2009 SIG A&D

Communication – Basic Techniques Become a friendlier person Win people to your way of thinking Change people’s attitude and behaviour (as a leader) [ ] February 5, 2009 SIG A&D

Become a friendlier person Don’t criticize, condemn or complain. Give honest and sincere appreciation. Arouse in the other person an eager want. Become genuinely interested in other people. Smile. Remember that a person’s name is to that person the sweetest and most important sound in any language. Be a good listener. Encourage others to talk about themselves. Talk in terms of the other person’s interests. Make the other person feel important. [ ] February 5, 2009 SIG A&D

Win people to your way of thinking The only way to get the best of an argument is to avoid it. Show respect for other’s opinions. Never say, “You’re wrong.” If you are wrong, admit it quickly and emphatically. Begin in a friendly way. Get the other person saying “yes, yes” immediately. Let the other person do a great deal of the talking. Let the other person feel that the idea is his or hers. Try to see things from someone else’s point of view. Be sympathetic with the other person’s ideas and desires. Appeal to the nobler motives. Dramatize your ideas. Throw down a challenge. [ ] February 5, 2009 SIG A&D

Change people’s attitude and behaviour Begin with praise and honest appreciation. Call attention to people’s mistakes indirectly. Talk about your own mistakes before criticizing someone else. Ask questions instead of giving direct orders. Let the other person save face. Praise even the slightest improvement. Give the other person a fine reputation to live up to. Use encouragement. Make a fault seem easy to correct. Make the other person happy about doing the thing you suggest. [ ] February 5, 2009 SIG A&D

Communication – Software Architecture specific? Hints: Ivory tower Start early (acceptance) Don’t forget maintenance (don’t stop) [ ] February 5, 2009 SIG A&D

Conclusion Documentation No documentation, no architecture We have seen the process, but still haven’t learned the techniques Communication Work on your communication skills. Information needs to be selected and shared, not just published. [ ] February 5, 2009 SIG A&D

References (1/2) “ Documenting Software Architectures – Views and Beyond”, Paul Clements, et al “ How to win friends & influence people”, Dale Carnegie [ ] February 5, 2009 SIG A&D Minutes of the Software Architect 2008 conference (3 rd -5 th June in London)

References (2/2) “ The Rational Unified Process – An introduction”, Philippe Kruchten [ ] February 5, 2009 SIG A&D http://www.slideshare.net/DavidMeijers IEEE Standard 1471

Sig A&D - Documentation And Communication

Recommended

More Related Content

Similar to Sig A&D - Documentation And Communication (20)

Recently uploaded (20)

Sig A&D - Documentation And Communication