Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Sig A&D - Documentation And Communication


Published on

Session #1 of the Special Interest Group Architecture & Design of 2009

Published in: Technology
  • Be the first to comment

Sig A&D - Documentation And Communication

  1. 1. SIG Architecture & Design Documentation and Communication of a Software Architecture David Meijers February 5, 2009
  2. 2. [ ] February 5, 2009 SIG A&D
  3. 3. Documentation – Introduction (1/2) [ ] February 5, 2009 SIG A&D Siemens Four Views RUP / Kruchten 4+1 Image: Lack of agility
  4. 4. Documentation – Introduction (2/2) <ul><li>This is not about ADL’s </li></ul><ul><li>(such ACME , Rapide, Wright, Unicon) </li></ul>[ ] 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; } }
  5. 5. 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.
  6. 6. 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.
  7. 7. Documentation guidelines <ul><li>Write from the reader’s point of view, not the writer’s </li></ul><ul><li>Avoid unnecessary repetition </li></ul><ul><li>Avoid ambiguity </li></ul><ul><li>Use a standard format </li></ul><ul><li>Record rationale </li></ul><ul><li>Keep documentation current but not too current </li></ul><ul><li>Review documentation for fitness of purpose </li></ul>[ ] February 5, 2009 SIG A&D
  8. 8. The Carnegie Mellon approach (1/2) <ul><li>Views and Styles </li></ul><ul><li>Viewtypes </li></ul><ul><li>How the system is structured as a set of implementation units </li></ul><ul><li>(module viewtype) </li></ul><ul><li>How the system is structured as a set of run-time interacting elements (component-and-connector viewtype) </li></ul><ul><li>How software structures correspond to system structures </li></ul><ul><li>(allocation viewtype) </li></ul>[ ] February 5, 2009 SIG A&D
  9. 9. Example: Module viewtype <ul><li>UML notation: </li></ul><ul><li>Elements </li></ul><ul><li>Relations </li></ul><ul><li>Properties </li></ul><ul><li>(of elements and </li></ul><ul><li>relations) </li></ul>[ ] February 5, 2009 SIG A&D
  10. 10. The Carnegie Mellon approach (2/2) <ul><li>Styles </li></ul><ul><li>Patterns of design decisions. </li></ul><ul><li>Module viewtype: </li></ul><ul><li>decomposition, layered, generalization </li></ul><ul><li>Component-and-connector viewtype: </li></ul><ul><li>shared-data, communicating-processes, client-server, pipe-and-filter </li></ul><ul><li>Allocation viewtype: </li></ul><ul><li>implementation, work assignment, deployment </li></ul>[ ] February 5, 2009 SIG A&D
  11. 11. Example: Implementation style <ul><li>Informal notation: </li></ul>[ ] February 5, 2009 SIG A&D
  12. 12. Process <ul><li>Create relevant views </li></ul><ul><li>Document them </li></ul><ul><li>Add documentation that applies to more than one view </li></ul>[ ] February 5, 2009 SIG A&D
  13. 13. So, what do we do specific for designers? [ ] February 5, 2009 SIG A&D <ul><li>Software Architecture vs Design </li></ul><ul><li>What is Design? </li></ul><ul><li>What is Software Architecture? </li></ul>
  14. 14. What is design? <ul><li>As a verb, </li></ul><ul><li>design is the activity of making such decisions. </li></ul><ul><li>...the resulting decision space may be large and complex. </li></ul><ul><li>As such, there is a science associated with design </li></ul><ul><li>(empirical analysis can point us to optimal regions or </li></ul><ul><li>exact points in this design space) as well as an art </li></ul><ul><li>(... degrees of freedom that range </li></ul><ul><li>beyond an empirical decision ...). </li></ul>[ ] 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
  15. 15. What is software architecture? <ul><li>&quot;Architecture&quot; is a term that lots of people try to define, </li></ul><ul><li>with little agreement. There are two common elements: </li></ul><ul><li>One is the highest-level breakdown of a system </li></ul><ul><li>into its parts; </li></ul><ul><li>the other, decisions that are hard to change. </li></ul><ul><li>Martin Fowler </li></ul>[ ] 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
  16. 16. No project is the same <ul><li>The role of an architect is highly contextual </li></ul><ul><li>But, the architect gets to define it </li></ul><ul><li>Pick the relevant views, the stakeholder will help </li></ul>[ ] February 5, 2009 SIG A&D 
  17. 17. Communication – Introduction <ul><li>Don’t you just hate it when an architecture is stuffed down your throat? </li></ul><ul><li>Does the architect ever talk to you? </li></ul><ul><li>Who is the architect anyway? </li></ul>[ ] February 5, 2009 SIG A&D
  18. 18. Communication – Basic Techniques <ul><li>Become a friendlier person </li></ul><ul><li>Win people to your way of thinking </li></ul><ul><li>Change people’s attitude and behaviour (as a leader) </li></ul>[ ] February 5, 2009 SIG A&D
  19. 19. Become a friendlier person <ul><li>Don’t criticize, condemn or complain. </li></ul><ul><li>Give honest and sincere appreciation. </li></ul><ul><li>Arouse in the other person an eager want. </li></ul><ul><li>Become genuinely interested in other people. </li></ul><ul><li>Smile. </li></ul><ul><li>Remember that a person’s name is to that person the sweetest and most important sound in any language. </li></ul><ul><li>Be a good listener. Encourage others to talk about themselves. </li></ul><ul><li>Talk in terms of the other person’s interests. </li></ul><ul><li>Make the other person feel important. </li></ul>[ ] February 5, 2009 SIG A&D
  20. 20. Win people to your way of thinking <ul><li>The only way to get the best of an argument is to avoid it. </li></ul><ul><li>Show respect for other’s opinions. Never say, “You’re wrong.” </li></ul><ul><li>If you are wrong, admit it quickly and emphatically. </li></ul><ul><li>Begin in a friendly way. </li></ul><ul><li>Get the other person saying “yes, yes” immediately. </li></ul><ul><li>Let the other person do a great deal of the talking. </li></ul><ul><li>Let the other person feel that the idea is his or hers. </li></ul><ul><li>Try to see things from someone else’s point of view. </li></ul><ul><li>Be sympathetic with the other person’s ideas and desires. </li></ul><ul><li>Appeal to the nobler motives. </li></ul><ul><li>Dramatize your ideas. </li></ul><ul><li>Throw down a challenge. </li></ul>[ ] February 5, 2009 SIG A&D
  21. 21. Change people’s attitude and behaviour <ul><li>Begin with praise and honest appreciation. </li></ul><ul><li>Call attention to people’s mistakes indirectly. </li></ul><ul><li>Talk about your own mistakes before criticizing someone else. </li></ul><ul><li>Ask questions instead of giving direct orders. </li></ul><ul><li>Let the other person save face. </li></ul><ul><li>Praise even the slightest improvement. </li></ul><ul><li>Give the other person a fine reputation to live up to. </li></ul><ul><li>Use encouragement. Make a fault seem easy to correct. </li></ul><ul><li>Make the other person happy about doing the thing you suggest. </li></ul>[ ] February 5, 2009 SIG A&D
  22. 22. Communication – Software Architecture specific? <ul><li>Hints: </li></ul><ul><li>Ivory tower </li></ul><ul><li>Start early (acceptance) </li></ul><ul><li>Don’t forget maintenance (don’t stop) </li></ul>[ ] February 5, 2009 SIG A&D
  23. 23. Conclusion <ul><li>Documentation </li></ul><ul><li>No documentation, no architecture </li></ul><ul><li>We have seen the process, but still haven’t learned the techniques </li></ul><ul><li>Communication </li></ul><ul><li>Work on your communication skills. </li></ul><ul><li>Information needs to be selected and shared, not just published. </li></ul>[ ] February 5, 2009 SIG A&D
  24. 24. References (1/2) <ul><li>“ Documenting Software Architectures – Views and Beyond”, Paul Clements, et al </li></ul><ul><li>“ How to win friends & influence people”, Dale Carnegie </li></ul>[ ] February 5, 2009 SIG A&D <ul><li>Minutes of the Software Architect 2008 conference (3 rd -5 th June in London) </li></ul>
  25. 25. References (2/2) <ul><li>“ The Rational Unified Process – An introduction”, Philippe Kruchten </li></ul>[ ] February 5, 2009 SIG A&D <ul><li> </li></ul><ul><li>IEEE Standard 1471 </li></ul>